{ "openapi": "3.1.0", "info": { "title": "openlaunch API", "version": "1.0.0", "description": "Provider-independent API for owner-managed device functions. Device attachment, agent access and function grants are separate permissions. Timestamps use Unix milliseconds. Most HTTP responses wrap data or error; health and OAuth metadata are raw objects. MCP uses its own JSON-RPC envelopes and protocol headers." }, "servers": [ { "url": "https://www.openlaunch.dev", "description": "Hosted API" } ], "tags": [ { "name": "System" }, { "name": "Owner" }, { "name": "Setup" }, { "name": "OAuth" }, { "name": "Agent" }, { "name": "Owner and agent" }, { "name": "Access" }, { "name": "Workspace" }, { "name": "Device" }, { "name": "MCP" } ], "paths": { "/healthz": { "get": { "summary": "Check service health", "tags": [ "System" ], "security": [], "responses": { "200": { "description": "Health fields; hosted includes deployment configuration, transport-neutral handler returns service and protocolVersion.", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string", "const": "openlaunch" }, "protocolVersion": { "type": "integer", "const": 1 }, "commit": { "type": "string" }, "authConfigured": { "type": "boolean" }, "deviceControlsEnabled": { "type": "boolean" } }, "required": [ "service", "protocolVersion" ] } } } } }, "description": "Inspect the hosted service and deployment configuration. Service health does not establish device health or physical execution. The local handler wraps its smaller health object in data.", "operationId": "getHealthz" } }, "/v1/account": { "get": { "summary": "Get signed-in owner account context", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Account" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Hosted owner endpoint. Agent tokens are not accepted as owner sessions.", "operationId": "getV1Account" } }, "/v1/devices": { "get": { "summary": "List visible devices", "tags": [ "Owner and agent" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Owner receives workspace devices. Agent receives only devices covered by current grants, with grant-filtered capabilities.", "x-codeSamples": [ { "lang": "Shell", "label": "ol CLI", "source": "ol devices list" }, { "lang": "TypeScript", "label": "openlaunch SDK", "source": "import { createClient } from \"@openlaunch/sdk\";\nconst agent = createClient({ url: process.env.OPENLAUNCH_URL ?? \"https://www.openlaunch.dev\", token: process.env.OPENLAUNCH_AGENT_TOKEN! });\nconst devices = await agent.listDevices();" } ], "operationId": "getV1Devices" } }, "/v1/actions": { "get": { "summary": "List action history", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActionHistory" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Owner-only; returns the most recent 100 actions.", "operationId": "getV1Actions" } }, "/v1/actions/export": { "get": { "summary": "Export action history", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/HistoryExport" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Download all retained owner action receipts, up to 5,000 entries within the workspace storage budget. Exporting does not remove history or idempotency protection.", "operationId": "getV1ActionsExport" } }, "/v1/actions/{actionId}": { "get": { "summary": "Get action state", "tags": [ "Owner and agent" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ActionReceipt" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Caller must be allowed the action's device function. The outcome can be unknown after disconnect; delivery is not exactly once.", "parameters": [ { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "ol CLI", "source": "ol actions get \"$ACTION_ID\"" }, { "lang": "TypeScript", "label": "openlaunch SDK", "source": "import { createClient } from \"@openlaunch/sdk\";\nconst agent = createClient({ url: process.env.OPENLAUNCH_URL ?? \"https://www.openlaunch.dev\", token: process.env.OPENLAUNCH_AGENT_TOKEN! });\nconst action = await agent.getAction(actionId);" }, { "lang": "Shell", "label": "ol CLI", "source": "ol actions watch \"$ACTION_ID\"" }, { "lang": "TypeScript", "label": "openlaunch SDK", "source": "import { createClient } from \"@openlaunch/sdk\";\nconst agent = createClient({ url: process.env.OPENLAUNCH_URL ?? \"https://www.openlaunch.dev\", token: process.env.OPENLAUNCH_AGENT_TOKEN! });\nconst terminal = new Set([\"succeeded\", \"failed\", \"expired\", \"cancelled\", \"unknown\"]);\nlet action; do { action = await agent.getAction(actionId); if (!terminal.has(action.status)) await new Promise(resolve => setTimeout(resolve, 1000)); } while (!terminal.has(action.status));" } ], "operationId": "getV1ActionsActionId" } }, "/v1/actions/{actionId}/cancel": { "post": { "summary": "Cancel queued action", "tags": [ "Owner and agent" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ActionReceipt" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Only queued, undispatched actions can be cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Requires action access and a current device grant. Only undispatched queued actions can be cancelled; cancellation cannot undo an action already received by a device.", "parameters": [ { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "Shell", "label": "ol CLI", "source": "ol actions cancel \"$ACTION_ID\"" }, { "lang": "TypeScript", "label": "openlaunch SDK", "source": "import { createClient } from \"@openlaunch/sdk\";\nconst agent = createClient({ url: process.env.OPENLAUNCH_URL ?? \"https://www.openlaunch.dev\", token: process.env.OPENLAUNCH_AGENT_TOKEN! });\nconst action = await agent.cancelAction(actionId);" } ], "operationId": "postV1ActionsActionIdCancel" } }, "/v1/functions": { "get": { "summary": "List callable functions", "tags": [ "Owner and agent" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Function" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Returns built-in and custom functions the caller currently has grants to invoke; owner sees available workspace functions. Every invocation is checked again against current grants and device argument schema.", "x-codeSamples": [ { "lang": "Shell", "label": "ol CLI", "source": "ol functions list" }, { "lang": "TypeScript", "label": "openlaunch SDK", "source": "import { createClient } from \"@openlaunch/sdk\";\nconst agent = createClient({ url: process.env.OPENLAUNCH_URL ?? \"https://www.openlaunch.dev\", token: process.env.OPENLAUNCH_AGENT_TOKEN! });\nconst functions = await agent.listFunctions();" } ], "operationId": "getV1Functions" } }, "/v1/agent-connections": { "get": { "summary": "List agent connections", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "List agent API connections in the owner's workspace, including their access ceiling and lifetime. Stored credential secrets are omitted.", "operationId": "getV1AgentConnections" }, "post": { "summary": "Create agent API connection", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "201": { "description": "Created; bearer token is returned once", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewConnection" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "ttlSeconds": { "default": 86400, "anyOf": [ { "type": "integer", "minimum": 60, "maximum": 2592000 }, { "type": "null" } ] }, "access": { "default": "act", "type": "string", "enum": [ "read", "act" ] }, "role": { "type": "string", "enum": [ "operator", "administrator" ] } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "automation", "ttlSeconds": 86400, "access": "act", "role": "operator" } } } }, "description": "Agent connections cannot attach devices. Access read/act is a ceiling; action calls also require a live per-device function grant. New connections are admitted with an all-devices operator access policy (opt-out exclusions can be set afterwards via /v1/access-policies); an explicit access read is preserved as the ceiling. Requesting role administrator requires an owner session. The token is returned once; if the access policy cannot be applied, the token is not issued and the pending connection is reconciled by the owner console.", "operationId": "postV1AgentConnections" } }, "/v1/device-setup-tokens": { "get": { "summary": "List device setup tokens", "tags": [ "Setup" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "The legacy sdk-tokens path aliases device-setup-tokens.", "operationId": "getV1DeviceSetupTokens" }, "post": { "summary": "Create attach-only device setup token", "tags": [ "Setup" ], "security": [ { "OwnerAuth": [] } ], "responses": { "201": { "description": "Created; setup token is returned once", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewConnection" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "ttlSeconds": { "default": 600, "type": "integer", "minimum": 60, "maximum": 86400 }, "deviceLimit": { "default": 1, "type": "integer", "minimum": 1, "maximum": 20 }, "gatewayDeviceLimit": { "type": "integer", "minimum": 0, "maximum": 2000 } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "bench device", "ttlSeconds": 600, "deviceLimit": 1 } } } }, "description": "Default lifetime is 10 minutes and default limit is one device. Setup credentials can only attach devices; attachment does not grant function access.", "operationId": "postV1DeviceSetupTokens" } }, "/v1/sdk-tokens": { "get": { "summary": "List setup tokens (legacy alias)", "tags": [ "Setup" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "The legacy sdk-tokens path aliases device-setup-tokens.", "operationId": "getV1SdkTokens" }, "post": { "summary": "Create setup token (legacy alias)", "tags": [ "Setup" ], "security": [ { "OwnerAuth": [] } ], "responses": { "201": { "description": "Created; setup token is returned once", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/NewConnection" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "ttlSeconds": { "default": 600, "type": "integer", "minimum": 60, "maximum": 86400 }, "deviceLimit": { "default": 1, "type": "integer", "minimum": 1, "maximum": 20 }, "gatewayDeviceLimit": { "type": "integer", "minimum": 0, "maximum": 2000 } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "bench device", "ttlSeconds": 600, "deviceLimit": 1 } } } }, "description": "Default lifetime is 10 minutes and default limit is one device. Setup credentials can only attach devices; attachment does not grant function access.", "operationId": "postV1SdkTokens" } }, "/v1/agent-connections/{connectionId}/revoke": { "post": { "summary": "Revoke agent connection", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ok" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "postV1AgentConnectionsConnectionIdRevoke" } }, "/v1/device-setup-tokens/{connectionId}/revoke": { "post": { "summary": "Revoke setup token", "tags": [ "Setup" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ok" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "postV1DeviceSetupTokensConnectionIdRevoke" } }, "/v1/sdk-tokens/{connectionId}/revoke": { "post": { "summary": "Revoke setup token (legacy alias)", "tags": [ "Setup" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ok" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "connectionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "postV1SdkTokensConnectionIdRevoke" } }, "/v1/oauth-clients": { "get": { "summary": "List OAuth clients", "tags": [ "OAuth" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "available": { "type": "boolean" }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } } }, "required": [ "available", "clients" ] } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "List registered OAuth clients in the owner's workspace and whether provider registration is available. Client secrets are never returned by this read.", "operationId": "getV1OauthClients" }, "post": { "summary": "Register OAuth client", "tags": [ "OAuth" ], "security": [ { "OwnerAuth": [] } ], "responses": { "201": { "description": "Created; client secret, when issued, appears only in this response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OAuthRegistration" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "redirectUris": { "type": "array", "minItems": 1, "maxItems": 8, "items": { "type": "string", "format": "uri" } }, "public": { "default": true, "type": "boolean" }, "access": { "default": "act", "type": "string", "enum": [ "read", "act" ] } }, "required": [ "name", "redirectUris" ], "additionalProperties": false } } } }, "description": "Exact HTTPS callbacks or literal loopback HTTP callbacks only. OAuth read/act scopes cap access but do not create device grants.", "operationId": "postV1OauthClients" } }, "/v1/oauth-clients/{clientId}/revoke": { "post": { "summary": "Revoke OAuth client", "tags": [ "OAuth" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/OAuthRevocation" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "clientId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "postV1OauthClientsClientIdRevoke" } }, "/v1/access-policies": { "get": { "summary": "List access policies", "tags": [ "Access" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccessPolicy" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Lists the workspace's delegation policies. The owner sees all; a delegated administrator sees the policies its live role permits. Legacy per-device grants are not listed here (see /v1/grants).", "operationId": "getV1AccessPolicies" }, "post": { "summary": "Set one principal's access policy", "tags": [ "Access" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AccessPolicy" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "principal": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^\\S+$" }, "mode": { "default": "all", "type": "string", "enum": [ "all", "selected" ] }, "excludedDevices": { "default": [], "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 } }, "excludedFunctions": { "default": [], "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "deviceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 128 }, { "type": "null" } ] }, "capability": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$" } }, "required": [ "deviceId", "capability" ], "additionalProperties": false } }, "role": { "default": "operator", "type": "string", "enum": [ "operator", "administrator" ] }, "expiresAt": { "default": null, "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "delegatedFrom": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^\\S+$" } }, "required": [ "principal" ], "additionalProperties": false }, "example": { "principal": "connection:00000000-0000-4000-8000-000000000001", "mode": "all", "excludedDevices": [], "excludedFunctions": [], "role": "operator", "expiresAt": null } } } }, "description": "Full-policy replacement for one principal. mode selected keeps the legacy per-device grant list; mode all covers every device with opt-out excludedDevices and excludedFunctions. Only the workspace owner can grant role administrator or set delegatedFrom ancestry; delegated administrators may update operator policies for other principals and can never modify their own policy.", "operationId": "postV1AccessPolicies" } }, "/v1/access": { "get": { "summary": "Inspect effective current access", "tags": [ "Access" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EffectiveAccess" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Returns the caller's effective policy after OAuth admission and policy application: role, device mode, opt-out exclusions and expiry. For mode selected the result reflects the live legacy per-device grants. Every request re-evaluates this before any handler or tool runs.", "operationId": "getV1Access" } }, "/v1/onboarding": { "get": { "summary": "Get onboarding status", "tags": [ "Access" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Onboarding" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Current devices, setup-token and agent-connection readiness, and suggested next steps computed from live hub state. Operators receive forbidden with the required next step.", "operationId": "getV1Onboarding" } }, "/v1/workspaces": { "get": { "summary": "List workspaces for the signed-in identity", "tags": [ "Workspace" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceMembership" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Hosted identity endpoint: workspaces this identity owns or has joined, with the role in each.", "operationId": "getV1Workspaces" } }, "/v1/workspaces/select": { "post": { "summary": "Select active workspace", "tags": [ "Workspace" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "workspace": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "workspace" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "workspace": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "workspace" ], "additionalProperties": false } } } }, "description": "Switches the signed-in identity's active workspace. Membership is required; agent API credentials are bound to one workspace and cannot switch.", "operationId": "postV1WorkspacesSelect" } }, "/v1/workspaces/accept": { "post": { "summary": "Accept workspace invitation", "tags": [ "Workspace" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceMembership" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "invitation": { "type": "string" } }, "required": [ "invitation" ], "additionalProperties": false } } } }, "description": "Redeems a one-time invitation secret and joins that workspace with the invited role. The invitation expires and records its redeemer; revoked members need explicit owner restoration.", "operationId": "postV1WorkspacesAccept" } }, "/v1/workspace/agents": { "get": { "summary": "List workspace members", "tags": [ "Workspace" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceAgent" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Owner or workspace administrator. Lists member identities with role and revoked status.", "operationId": "getV1WorkspaceAgents" } }, "/v1/workspace/invitations": { "post": { "summary": "Invite a workspace member", "tags": [ "Workspace" ], "security": [ { "OwnerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/WorkspaceInvitation" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "role": { "type": "string", "enum": [ "operator", "administrator" ], "default": "operator" }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 3600, "default": 600 } }, "required": [ "name" ], "additionalProperties": false } } } }, "description": "Creates a one-time invitation. Only the workspace owner can delegate administration (role administrator). The invitation secret is shown once and stored only as a hash.", "operationId": "postV1WorkspaceInvitations" } }, "/v1/workspace/agents/{agentId}/revoke": { "post": { "summary": "Revoke workspace member", "tags": [ "Workspace" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ok" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "agentId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^agent:[a-f0-9]{64}$" } } ], "description": "Owner or workspace administrator; a member cannot revoke itself. The member's live policy denies all functions immediately and its bound credentials are revoked.", "operationId": "postV1WorkspaceAgentsAgentIdRevoke" } }, "/v1/cli-login/authorize": { "post": { "summary": "Authorize CLI login", "tags": [ "Workspace" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CliAuthorization" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "callbackUrl": { "type": "string", "format": "uri", "description": "Exact 127.0.0.1 loopback callback URL with a port." }, "state": { "type": "string" }, "challenge": { "type": "string", "description": "PKCE S256 challenge." } }, "required": [ "callbackUrl", "state", "challenge" ], "additionalProperties": false } } } }, "description": "Starts a CLI login for the signed-in identity: returns a one-time code delivered to the loopback callback, valid for 60 seconds.", "operationId": "postV1CliLoginAuthorize" } }, "/v1/cli-login/exchange": { "post": { "summary": "Exchange CLI login code", "tags": [ "Workspace" ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CliLoginExchange" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "verifier": { "type": "string", "description": "PKCE verifier." } }, "required": [ "code", "verifier" ], "additionalProperties": false } } } }, "description": "Unauthenticated exchange: the one-time code plus PKCE verifier is the credential. Returns the agent connection token once, bound to the caller's workspace with a policy delegated from the parent principal (persistent ancestry enforced server-side). Owner review covers privilege amplification.", "operationId": "postV1CliLoginExchange" } }, "/v1/grants": { "get": { "summary": "List grants", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CapabilityGrant" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Owner-only; lists active grants for non-revoked devices.", "operationId": "getV1Grants" }, "post": { "summary": "Grant device functions", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ok" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "principal": { "type": "string", "minLength": 1, "maxLength": 128 }, "deviceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "capabilities": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$" } }, "ttlSeconds": { "default": 3600, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] } }, "required": [ "principal", "deviceId", "capabilities" ], "additionalProperties": false } } } }, "description": "Only an owner can grant. Grants are per principal and device, limited to 64 capabilities for Home Assistant linked devices, 24 for Linux and 16 for other kinds, default to one hour and may be made persistent with null expiry.", "operationId": "postV1Grants" } }, "/v1/grants/revoke": { "post": { "summary": "Revoke device function grant", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ok" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "principal": { "type": "string" }, "deviceId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "principal", "deviceId" ], "additionalProperties": false } } } }, "description": "Remove this principal's device grant. Later agent requests are denied, queued commands are cancelled and already received outcomes remain uncertain.", "operationId": "postV1GrantsRevoke" } }, "/v1/enrollments": { "post": { "summary": "Create legacy board enrollment", "tags": [ "Setup" ], "security": [ { "OwnerAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Enrollment" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "kind": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" } }, "required": [ "kind" ], "additionalProperties": false } } } }, "description": "Legacy board-bound enrollment code is single use and expires after 10 minutes.", "operationId": "postV1Enrollments" } }, "/v1/device/enroll": { "post": { "summary": "Enroll legacy board", "tags": [ "Setup" ], "security": [], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AttachedDevice" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "minLength": 64, "maxLength": 64 }, "manifest": { "$ref": "#/components/schemas/Manifest" } }, "required": [ "token", "manifest" ], "additionalProperties": false }, "example": { "token": "", "manifest": { "name": "board", "kind": "uno-r4-wifi", "capabilities": [ "device.health" ] } } } } }, "description": "Legacy enrollment route; code is single use and expires after 10 minutes.", "parameters": [ { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "operationId": "postV1DeviceEnroll" } }, "/v1/sdk/devices": { "post": { "summary": "Attach SDK device", "tags": [ "Setup" ], "security": [ { "SetupAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/AttachedDevice" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Attachment retry expired or request ID reused with a different manifest", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "manifest": { "$ref": "#/components/schemas/Manifest" } }, "required": [ "requestId", "manifest" ], "additionalProperties": false }, "example": { "requestId": "00000000-0000-4000-8000-000000000001", "manifest": { "name": "board", "kind": "uno-r4-wifi", "capabilities": [ "device.health" ] } } } } }, "description": "Requires an attach-only setup token. requestId enables recovery of a lost response for 10 minutes when the manifest fingerprint is unchanged. It creates no function grants.", "operationId": "postV1SdkDevices" } }, "/v1/devices/{deviceId}/revoke": { "post": { "summary": "Revoke device", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Ok" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "description": "Revokes the child device credential and cancels queued actions.", "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "operationId": "postV1DevicesDeviceIdRevoke" } }, "/v1/devices/{deviceId}/actions": { "post": { "summary": "Request device action", "tags": [ "Agent" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "202": { "description": "Accepted into queue", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ActionReceipt" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Idempotency key conflict, device offline, or action cannot proceed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capability": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$" }, "arguments": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 128 }, "ttlSeconds": { "default": 30, "type": "integer", "minimum": 1, "maximum": 300 } }, "required": [ "capability", "arguments", "idempotencyKey" ], "additionalProperties": false }, "example": { "capability": "device.health", "arguments": {}, "idempotencyKey": "request-001", "ttlSeconds": 30 } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Requires action scope for OAuth callers and a current per-device capability grant. Idempotency key is 1–128 characters; TTL defaults to 30 seconds and is at most 300 seconds. Duplicate retries with the same key and identical request return the existing receipt; key reuse with a different request conflicts. Physical execution is not exactly once.", "x-codeSamples": [ { "lang": "Shell", "label": "ol CLI", "source": "ol call \"$DEVICE_ID\" device.health '{}' --key health-001" }, { "lang": "TypeScript", "label": "openlaunch SDK", "source": "import { createClient } from \"@openlaunch/sdk\";\nconst agent = createClient({ url: process.env.OPENLAUNCH_URL ?? \"https://www.openlaunch.dev\", token: process.env.OPENLAUNCH_AGENT_TOKEN! });\nconst receipt = await agent.requestAction(deviceId, { capability: \"device.health\", arguments: {}, idempotencyKey: \"health-001\" });" } ], "operationId": "postV1DevicesDeviceIdActions" } }, "/v1/broadcasts": { "post": { "summary": "Request action on multiple devices", "tags": [ "Agent" ], "security": [ { "OwnerAuth": [] }, { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "202": { "description": "Each device has an independent action or error", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BroadcastResult" } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "Individual device actions can conflict; inspect each result item", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceIds": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "capability": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$" }, "arguments": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "idempotencyKey": { "type": "string", "minLength": 1, "maxLength": 64 }, "ttlSeconds": { "default": 30, "type": "integer", "minimum": 1, "maximum": 300 } }, "required": [ "deviceIds", "capability", "arguments", "idempotencyKey" ], "additionalProperties": false } } } }, "description": "Up to 20 devices. Per-device authorization and schema checks apply. Results are independent; broadcast is not atomic. TTL defaults to 30 seconds and is at most 300 seconds.", "x-codeSamples": [ { "lang": "Shell", "label": "curl", "source": "curl -X POST \"${OPENLAUNCH_URL:-https://www.openlaunch.dev}/v1/broadcasts\" -H \"Authorization: Bearer $OPENLAUNCH_AGENT_TOKEN\" -H 'Content-Type: application/json' -d '{\"deviceIds\":[\"00000000-0000-4000-8000-000000000001\"],\"capability\":\"device.health\",\"arguments\":{},\"idempotencyKey\":\"broadcast-001\"}'" }, { "lang": "TypeScript", "label": "openlaunch SDK", "source": "import { createClient } from \"@openlaunch/sdk\";\nconst agent = createClient({ url: process.env.OPENLAUNCH_URL ?? \"https://www.openlaunch.dev\", token: process.env.OPENLAUNCH_AGENT_TOKEN! });\nconst results = await agent.broadcast({ deviceIds, capability: \"device.health\", arguments: {}, idempotencyKey: \"broadcast-001\" });" } ], "operationId": "postV1Broadcasts" } }, "/v1/device/{deviceId}/manifest": { "post": { "summary": "Publish device manifest", "tags": [ "Device" ], "security": [ { "DeviceAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ManifestUpdate" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "manifest": { "$ref": "#/components/schemas/Manifest" } }, "required": [ "manifest" ], "additionalProperties": false }, "example": { "manifest": { "name": "board", "kind": "uno-r4-wifi", "capabilities": [ "device.health" ] } } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Manifest changes require owner reapproval: prior grants are revoked, queued actions are cancelled, and received action outcomes remain uncertain.", "operationId": "postV1DeviceDeviceIdManifest" } }, "/v1/device/{deviceId}/next": { "post": { "summary": "Poll for next action", "tags": [ "Device" ], "security": [ { "DeviceAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/DeviceNext" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Returns a queued command and marks it received, or null when no command is available. Device reports the correlated result over HTTPS.", "operationId": "postV1DeviceDeviceIdNext" } }, "/v1/devices/{deviceId}/gateway-grants": { "post": { "summary": "Grant current gateway inventory", "tags": [ "Owner" ], "security": [ { "OwnerAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "devices": { "type": "integer" } }, "required": [ "ok", "devices" ] } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "principal": { "type": "string", "minLength": 1, "maxLength": 128 }, "mode": { "type": "string", "enum": [ "read", "control" ] }, "includeServices": { "default": false, "type": "boolean" }, "ttlSeconds": { "default": 3600, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] } }, "required": [ "principal", "mode" ], "additionalProperties": false } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "description": "Owner-only convenience for current gateway and linked devices. Mode read grants read functions; control grants all. Integration-wide HA service devices require includeServices. Future devices remain ungranted. Replaces this principal’s grants for this gateway and its children; omitted service devices lose previous grants and their queued commands are cancelled. Other gateways are unaffected. Per-device grants remain independently revocable.", "operationId": "postV1DevicesDeviceIdGatewayGrants" } }, "/v1/device/{deviceId}/children": { "post": { "summary": "Discover gateway devices", "tags": [ "Device" ], "security": [ { "DeviceAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "deviceId": { "type": "string", "format": "uuid" }, "revoked": { "type": "boolean" }, "grantsRevoked": { "type": "boolean" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "key" ] } } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "children": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 192, "pattern": "^[a-zA-Z0-9_.:-]+$" }, "manifest": {} }, "required": [ "key", "manifest" ], "additionalProperties": false } } }, "required": [ "children" ], "additionalProperties": false } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Upsert up to eight gateway-owned devices by stable key. Only a gateway admitted with an owner-set child limit may call this route. No grants or child credentials are issued. Changed manifests revoke grants; owner-revoked children cannot be revived. A batch returns an independent result/error per child. Authenticated gateway requests allow up to 64 KiB.", "operationId": "postV1DeviceDeviceIdChildren" } }, "/v1/device/{deviceId}/children/status": { "post": { "summary": "Report gateway connectivity and inventory", "tags": [ "Device" ], "security": [ { "DeviceAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "online": { "type": "boolean" }, "keys": { "maxItems": 2000, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 192, "pattern": "^[a-zA-Z0-9_.:-]+$" } } }, "required": [ "online" ], "additionalProperties": false } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Report the upstream connection separately from gateway presence. Optional keys are the complete current inventory; missing children lose their grants and queued work is cancelled. Transient upstream disconnection without keys preserves grants. Revoking the gateway revokes all children. Authenticated gateway inventory reconciliation allows up to 512 KiB for a complete bounded key list.", "operationId": "postV1DeviceDeviceIdChildrenStatus" } }, "/v1/device/{deviceId}/heartbeat": { "post": { "summary": "Refresh device presence", "tags": [ "Device" ], "security": [ { "DeviceAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "lastSeen": { "type": "integer" } }, "required": [ "lastSeen" ] } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Authenticated presence only. Does not fetch, dispatch, complete or replay an action, extend its expiry, or change any grant. Used during long execution when ordinary device polling is paused.", "operationId": "postV1DeviceDeviceIdHeartbeat" } }, "/v1/device/{deviceId}/result": { "post": { "summary": "Report action result", "tags": [ "Device" ], "security": [ { "DeviceAuth": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ActionReceipt" } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "actionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "result": {} }, "required": [ "actionId", "status", "result" ], "additionalProperties": false } } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Correlated outcome can be succeeded or failed. Request bodies are limited to 16 KiB, except authenticated Linux result uploads up to 64 KiB. Only desktop.screenshot may return up to 48 KiB of UTF-8 JSON; other results retain their 4096-character limit. Results must fit the workspace's 16 MiB logical storage budget. Exact repeats are idempotent; conflicting repeats are rejected. Delivery does not guarantee exactly-once physical execution.", "operationId": "postV1DeviceDeviceIdResult" } }, "/v1/device/{deviceId}/events-ticket": { "post": { "summary": "Issue one-use WebSocket ticket", "tags": [ "Device" ], "security": [ { "DeviceAuth": [] } ], "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "ticket": { "type": "string" }, "expiresAt": { "type": "integer" } }, "required": [ "ticket", "expiresAt" ] } }, "additionalProperties": false } } } }, "400": { "description": "Invalid request or validation failure", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Missing or invalid credential", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Insufficient access or grant", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "Request body exceeds the 16 KiB limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "Rate limit or workspace capacity limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Service or required integration is not configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "maxProperties": 0, "additionalProperties": false }, "example": {} } } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Ticket expires after 30 seconds. Pass as the ticket.* WebSocket subprotocol during handshake; never put it in a URL query.", "operationId": "postV1DeviceDeviceIdEventsTicket" } }, "/v1/device/{deviceId}/events": { "get": { "summary": "Open device wake WebSocket", "tags": [ "Device" ], "security": [ { "TicketSubprotocol": [] } ], "responses": { "101": { "description": "WebSocket upgrade. Sends payload-free work hints; read actions and report outcomes over HTTPS." } }, "parameters": [ { "name": "deviceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "workspace", "in": "query", "required": true, "description": "Public workspace routing identifier; not a credential.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, { "name": "x-openlaunch-workspace", "in": "header", "required": true, "description": "Workspace routing identifier for the device credential; not a secret. Must match the workspace query parameter.", "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "description": "Interactive OpenAPI clients cannot establish this WebSocket upgrade. Offer subprotocols openlaunch.device-events.v1 and ticket.; the ticket expires after 30 seconds and is consumed once. Do not send a bearer header or put the secret ticket in a URL query. The channel carries no action payload.", "operationId": "getV1DeviceDeviceIdEvents" } }, "/.well-known/oauth-protected-resource": { "get": { "summary": "OAuth protected resource metadata", "tags": [ "OAuth" ], "security": [], "responses": { "200": { "description": "Protected resource metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string", "enum": [ "openlaunch:read", "openlaunch:act" ] } } }, "required": [ "resource", "authorization_servers", "scopes_supported" ] } } } } }, "operationId": "getWellKnownOauthProtectedResource" } }, "/.well-known/oauth-protected-resource/mcp": { "get": { "summary": "MCP OAuth metadata path alias", "tags": [ "OAuth" ], "security": [], "responses": { "200": { "description": "Protected resource metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string", "enum": [ "openlaunch:read", "openlaunch:act" ] } } }, "required": [ "resource", "authorization_servers", "scopes_supported" ] } } } } }, "operationId": "getWellKnownOauthProtectedResourceMcp" } }, "/mcp": { "post": { "summary": "Call authenticated MCP endpoint", "tags": [ "MCP" ], "security": [ { "AgentAuth": [] }, { "OAuthAuth": [] } ], "responses": { "200": { "description": "MCP JSON response or server-sent event stream" }, "400": { "description": "JSON-RPC or MCP protocol error" }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "Scope or live device grant required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false } } } }, "406": { "description": "Accept must include application/json and text/event-stream" }, "415": { "description": "Content-Type must be application/json" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "MCP JSON-RPC request. 2026-07-28 per-request protocol requires matching MCP-Protocol-Version and MCP-Method headers plus matching metadata; legacy Streamable HTTP initialization handshake remains supported.", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "integer", "string" ] }, "method": { "type": "string" }, "params": { "type": "object", "additionalProperties": true } } }, "example": { "jsonrpc": "2.0", "id": 1, "method": "server/discover", "params": { "_meta": { "io.modelcontextprotocol/protocolVersion": "2026-07-28", "io.modelcontextprotocol/clientCapabilities": {} } } } } } }, "description": "OAuth scopes read/act bound access but do not grant device functions. Every device tool also checks current owner grant. The separate public /docs-mcp service is read-only documentation.", "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "schema": { "type": "string" }, "example": "2026-07-28", "description": "Required for modern requests; must match params._meta protocolVersion." }, { "name": "Mcp-Method", "in": "header", "schema": { "type": "string" }, "example": "server/discover", "description": "Required for modern requests; must match the JSON-RPC method." }, { "name": "Mcp-Name", "in": "header", "schema": { "type": "string" }, "description": "Required for modern tools/call and resources/read; match tool name or resource URI. Unicode values use the protocol's base64 header encoding." } ], "operationId": "postMcp" } } }, "components": { "securitySchemes": { "OwnerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "Clerk owner session", "description": "Owner identity required." }, "AgentAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ol_agent token", "description": "Owner-issued agent API connection; access ceiling and live device grants are checked separately." }, "OAuthAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "OAuth access token", "description": "OAuth read/act scope is a ceiling. Scopes do not create device grants." }, "SetupAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "ol_sdk setup token", "description": "Attach-only credential with a finite device limit. Attachment does not grant functions." }, "DeviceAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "device child credential", "description": "Child device credential, independently revocable from its setup token." }, "TicketSubprotocol": { "type": "apiKey", "in": "header", "name": "Sec-WebSocket-Protocol", "description": "Offer openlaunch.device-events.v1, ticket.. The ticket comes from the authenticated events-ticket endpoint, expires in 30 seconds, and is never a URL query parameter." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } }, "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": false }, "ActionReceipt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deviceId": { "type": "string", "format": "uuid" }, "capability": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "queued", "received", "succeeded", "failed", "expired", "cancelled", "unknown" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "dispatchedAt": { "type": "integer" }, "resultReceivedAt": { "type": "integer", "description": "Server time in Unix milliseconds when the first terminal device result was saved. Preserved on identical retries; absent for older receipts. This is receipt delivery, not physical completion." }, "result": {}, "clientKey": { "type": "string", "description": "Internal idempotency key stored in the action ledger; included by request/get/result handler responses." }, "fingerprint": { "type": "string", "description": "Internal canonical request fingerprint; included by request/get/result and action history responses." }, "principalId": { "type": "string", "description": "Principal identifier associated with the action." }, "ownerAuthorized": { "type": "boolean", "description": "Internal provenance: true for an owner-originated action. False is normal for an accepted agent action whose live grants authorize it; it is not a missing-approval status. MCP receipts omit this field." }, "accessPolicy": { "type": "string", "description": "Policy principal that authorized this action when queued; dispatch re-checks the live chain for that policy before delivering." }, "accessConstraints": { "type": "array", "items": { "type": "string" }, "description": "Constraint principals (e.g. the original OAuth client of a linked membership) re-checked against their live policies at dispatch time." } }, "required": [ "id", "deviceId", "capability", "args", "status", "createdAt", "expiresAt", "clientKey", "fingerprint", "principalId", "ownerAuthorized" ], "additionalProperties": false }, "ActionHistory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deviceId": { "type": "string", "format": "uuid" }, "capability": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "queued", "received", "succeeded", "failed", "expired", "cancelled", "unknown" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "dispatchedAt": { "type": "integer" }, "resultReceivedAt": { "type": "integer", "description": "Server time in Unix milliseconds when the first terminal device result was saved. Preserved on identical retries; absent for older receipts. This is receipt delivery, not physical completion." }, "result": {}, "fingerprint": { "type": "string", "description": "Internal canonical request fingerprint; included by request/get/result and action history responses." }, "principalId": { "type": "string", "description": "Principal identifier associated with the action." }, "ownerAuthorized": { "type": "boolean", "description": "Internal provenance: true for an owner-originated action. False is normal for an accepted agent action whose live grants authorize it; it is not a missing-approval status. MCP receipts omit this field." }, "accessPolicy": { "type": "string", "description": "Policy principal that authorized this action when queued; dispatch re-checks the live chain for that policy before delivering." }, "accessConstraints": { "type": "array", "items": { "type": "string" }, "description": "Constraint principals (e.g. the original OAuth client of a linked membership) re-checked against their live policies at dispatch time." } }, "required": [ "id", "deviceId", "capability", "args", "status", "createdAt", "expiresAt", "fingerprint", "principalId", "ownerAuthorized" ], "additionalProperties": false }, "ActionExport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deviceId": { "type": "string", "format": "uuid" }, "capability": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "queued", "received", "succeeded", "failed", "expired", "cancelled", "unknown" ] }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "dispatchedAt": { "type": "integer" }, "resultReceivedAt": { "type": "integer", "description": "Server time in Unix milliseconds when the first terminal device result was saved. Preserved on identical retries; absent for older receipts. This is receipt delivery, not physical completion." }, "result": {}, "principalId": { "type": "string", "description": "Principal identifier associated with the action." }, "ownerAuthorized": { "type": "boolean", "description": "Internal provenance: true for an owner-originated action. False is normal for an accepted agent action whose live grants authorize it; it is not a missing-approval status. MCP receipts omit this field." }, "accessPolicy": { "type": "string", "description": "Policy principal that authorized this action when queued; dispatch re-checks the live chain for that policy before delivering." }, "accessConstraints": { "type": "array", "items": { "type": "string" }, "description": "Constraint principals (e.g. the original OAuth client of a linked membership) re-checked against their live policies at dispatch time." } }, "required": [ "id", "deviceId", "capability", "args", "status", "createdAt", "expiresAt", "principalId", "ownerAuthorized" ], "additionalProperties": false }, "Device": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "functions": { "type": "array", "items": { "$ref": "#/components/schemas/FunctionDefinition" } }, "lastSeen": { "type": "integer" }, "revoked": { "type": "boolean" }, "online": { "type": "boolean" }, "gatewayId": { "type": "string", "format": "uuid" }, "gatewayKey": { "type": "string" }, "gatewayAvailable": { "type": "boolean" }, "gatewayConnected": { "type": "boolean" }, "gatewayDeviceLimit": { "type": "integer", "maximum": 2000 } }, "required": [ "id", "name", "kind", "capabilities", "lastSeen", "revoked", "online" ], "additionalProperties": true }, "Manifest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "kind": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$" }, "capabilities": { "minItems": 1, "maxItems": 64, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$" } }, "functions": { "maxItems": 64, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "minLength": 1, "maxLength": 240 }, "access": { "type": "string", "enum": [ "read", "write" ] }, "inputSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object" }, "properties": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,47}$" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "string" }, "description": { "type": "string", "maxLength": 240 }, "minLength": { "type": "integer", "minimum": 0, "maximum": 8192 }, "maxLength": { "type": "integer", "minimum": 0, "maximum": 8192 }, "enum": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 1024 } } }, "required": [ "type", "maxLength" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "number", "integer" ] }, "description": { "type": "string", "maxLength": 240 }, "minimum": { "type": "number" }, "maximum": { "type": "number" } }, "required": [ "type", "minimum", "maximum" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "description": { "type": "string", "maxLength": 240 } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "object" }, "description": { "type": "string", "maxLength": 240 }, "maxProperties": { "type": "integer", "minimum": 1, "maximum": 32 }, "additionalProperties": { "type": "boolean", "const": true } }, "required": [ "type", "maxProperties", "additionalProperties" ], "additionalProperties": false } ] } }, "required": { "maxItems": 16, "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean", "const": false } }, "required": [ "type", "properties", "required", "additionalProperties" ], "additionalProperties": false } }, "required": [ "name", "title", "description", "access", "inputSchema" ], "additionalProperties": false } } }, "required": [ "name", "kind", "capabilities" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "kind": { "const": "linux" } }, "required": [ "kind" ] }, "then": { "properties": { "capabilities": { "maxItems": 24 }, "functions": { "maxItems": 24 } } } }, { "if": { "properties": { "kind": { "not": { "anyOf": [ { "const": "linux" }, { "pattern": "^home-assistant\\." } ] } } }, "required": [ "kind" ] }, "then": { "properties": { "capabilities": { "maxItems": 16 }, "functions": { "maxItems": 16 } } } }, { "if": { "properties": { "kind": { "not": { "const": "linux" } } }, "required": [ "kind" ] }, "then": { "properties": { "functions": { "items": { "properties": { "inputSchema": { "properties": { "properties": { "additionalProperties": { "if": { "properties": { "type": { "const": "string" } }, "required": [ "type" ] }, "then": { "properties": { "maxLength": { "maximum": 1024 }, "minLength": { "maximum": 1024 } } } } } } } } } } } } }, { "if": { "properties": { "kind": { "not": { "pattern": "^home-assistant\\." } } }, "required": [ "kind" ] }, "then": { "properties": { "functions": { "items": { "properties": { "inputSchema": { "properties": { "properties": { "additionalProperties": { "not": { "properties": { "type": { "const": "object" } }, "required": [ "type" ] } } } } } } } } } } } ] }, "FunctionDefinition": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-z][a-z0-9_]*(?:\\.[a-z][a-z0-9_]*)*$" }, "title": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": { "type": "string", "minLength": 1, "maxLength": 240 }, "access": { "type": "string", "enum": [ "read", "write" ] }, "inputSchema": { "type": "object", "properties": { "type": { "type": "string", "const": "object" }, "properties": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,47}$" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "string" }, "description": { "type": "string", "maxLength": 240 }, "minLength": { "type": "integer", "minimum": 0, "maximum": 8192 }, "maxLength": { "type": "integer", "minimum": 0, "maximum": 8192 }, "enum": { "minItems": 1, "maxItems": 32, "type": "array", "items": { "type": "string", "maxLength": 1024 } } }, "required": [ "type", "maxLength" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "number", "integer" ] }, "description": { "type": "string", "maxLength": 240 }, "minimum": { "type": "number" }, "maximum": { "type": "number" } }, "required": [ "type", "minimum", "maximum" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "description": { "type": "string", "maxLength": 240 } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "object" }, "description": { "type": "string", "maxLength": 240 }, "maxProperties": { "type": "integer", "minimum": 1, "maximum": 32 }, "additionalProperties": { "type": "boolean", "const": true } }, "required": [ "type", "maxProperties", "additionalProperties" ], "additionalProperties": false } ] } }, "required": { "maxItems": 16, "type": "array", "items": { "type": "string" } }, "additionalProperties": { "type": "boolean", "const": false } }, "required": [ "type", "properties", "required", "additionalProperties" ], "additionalProperties": false } }, "required": [ "name", "title", "description", "access", "inputSchema" ], "additionalProperties": false }, "CapabilityGrant": { "type": "object", "properties": { "principal": { "type": "string" }, "deviceId": { "type": "string", "format": "uuid" }, "capabilities": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": [ "integer", "null" ] } }, "required": [ "principal", "deviceId", "capabilities", "expiresAt" ] }, "AgentConnection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "principal": { "type": "string" }, "name": { "type": "string" }, "expiresAt": { "type": [ "integer", "null" ] }, "revoked": { "type": "boolean" }, "access": { "type": "string", "enum": [ "read", "act" ] }, "purpose": { "type": "string", "enum": [ "agent", "device-setup", "oauth" ] }, "canAttach": { "type": "boolean" }, "deviceLimit": { "type": "integer" }, "gatewayDeviceLimit": { "type": "integer" }, "attachedDeviceCount": { "type": "integer" }, "oauth": { "type": "object", "properties": { "applicationId": { "type": "string" }, "clientId": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "public": { "type": "boolean" } }, "required": [ "applicationId", "clientId", "redirectUris", "public" ], "additionalProperties": false } }, "required": [ "id", "principal", "name", "expiresAt", "revoked", "access" ] }, "Function": { "type": "object", "properties": { "deviceId": { "type": "string", "format": "uuid" }, "deviceName": { "type": "string" }, "kind": { "type": "string" }, "definition": { "$ref": "#/components/schemas/FunctionDefinition" }, "guide": { "type": "string" } }, "required": [ "deviceId", "deviceName", "kind", "definition", "guide" ] }, "AccessPolicy": { "type": "object", "properties": { "principal": { "type": "string" }, "mode": { "type": "string", "enum": [ "all", "selected" ], "description": "selected keeps the legacy per-device grant list; all covers every workspace device with opt-out exclusions." }, "excludedDevices": { "type": "array", "items": { "type": "string" } }, "excludedFunctions": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": [ "string", "null" ] }, "capability": { "type": "string" } }, "required": [ "deviceId", "capability" ], "additionalProperties": false } }, "role": { "type": "string", "enum": [ "operator", "administrator" ] }, "expiresAt": { "type": [ "integer", "null" ] }, "delegatedFrom": { "type": "string", "description": "Parent policy principal this policy was delegated from; a child is always intersected with the live parent chain, so delegated credentials can never escape parent exclusions, expiry or role changes." } }, "required": [ "principal", "mode", "excludedDevices", "excludedFunctions", "role", "expiresAt" ], "additionalProperties": false }, "EffectiveAccess": { "type": "object", "description": "The caller's effective current access: policy role and mode plus, for selected mode, the live legacy per-device grants.", "properties": { "principal": { "type": "string" }, "role": { "type": [ "string", "null" ], "enum": [ "operator", "administrator", null ] }, "mode": { "type": [ "string", "null" ], "enum": [ "all", "selected", null ] }, "readOnly": { "type": "boolean" }, "excludedDevices": { "type": "array", "items": { "type": "string" } }, "excludedFunctions": { "type": "array", "items": { "type": "object", "properties": { "deviceId": { "type": [ "string", "null" ] }, "capability": { "type": "string" } }, "required": [ "deviceId", "capability" ], "additionalProperties": false } }, "expiresAt": { "type": [ "integer", "null" ] }, "delegatedFrom": { "type": "string" } }, "required": [ "principal", "role" ], "additionalProperties": true }, "Onboarding": { "type": "object", "properties": { "devices": { "type": "array", "items": { "$ref": "#/components/schemas/Device" } }, "setup": { "type": "object", "properties": { "attachmentConfigured": { "type": "boolean", "description": "Server-side device attachment credentials are configured." }, "setupTokens": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } }, "agentConnections": { "type": "array", "items": { "$ref": "#/components/schemas/AgentConnection" } } }, "required": [ "attachmentConfigured", "setupTokens", "agentConnections" ], "additionalProperties": false }, "nextSteps": { "type": "array", "items": { "type": "string" } } }, "required": [ "devices", "setup", "nextSteps" ], "additionalProperties": false }, "WorkspaceMembership": { "type": "object", "properties": { "workspace": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "principalId": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "operator", "administrator" ] } }, "required": [ "workspace", "principalId", "name", "role" ], "additionalProperties": false }, "WorkspaceAgent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^agent:[a-f0-9]{64}$" }, "identityId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "operator", "administrator" ] }, "joinedAt": { "type": "integer" }, "revoked": { "type": "boolean" } }, "required": [ "id", "identityId", "name", "role", "joinedAt", "revoked" ], "additionalProperties": false }, "WorkspaceInvitation": { "type": "object", "properties": { "invitation": { "type": "string", "description": "One-time invitation secret; shown once, stored only as a hash, expires at expiresAt." }, "expiresAt": { "type": "integer" } }, "required": [ "invitation", "expiresAt" ], "additionalProperties": false }, "CliAuthorization": { "type": "object", "properties": { "code": { "type": "string", "description": "One-time login code; consumed by the exchange call." }, "state": { "type": "string" }, "callbackUrl": { "type": "string", "format": "uri" } }, "required": [ "code", "state", "callbackUrl" ], "additionalProperties": false }, "CliLoginExchange": { "type": "object", "properties": { "token": { "type": "string", "description": "Agent connection credential; shown once by this response. Store securely, never log or commit." }, "workspace": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "connectionId": { "type": "string", "format": "uuid" }, "expiresAt": { "type": [ "integer", "null" ] }, "access": { "type": "string", "enum": [ "read", "act" ] }, "role": { "type": "string", "enum": [ "operator", "administrator" ] } }, "required": [ "token", "workspace", "connectionId", "expiresAt", "access", "role" ], "additionalProperties": false }, "NewConnection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "principal": { "type": "string" }, "name": { "type": "string" }, "expiresAt": { "type": [ "integer", "null" ] }, "revoked": { "type": "boolean" }, "access": { "type": "string", "enum": [ "read", "act" ] }, "oauth": { "type": "object", "properties": { "applicationId": { "type": "string" }, "clientId": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "public": { "type": "boolean" } }, "required": [ "applicationId", "clientId", "redirectUris", "public" ], "additionalProperties": false }, "purpose": { "type": "string", "enum": [ "agent", "device-setup" ] }, "canAttach": { "type": "boolean" }, "deviceLimit": { "type": "integer" }, "gatewayDeviceLimit": { "type": "integer" }, "attachedDeviceCount": { "type": "integer" }, "token": { "type": "string", "description": "Returned once. Store securely; never log or commit." } }, "required": [ "id", "principal", "name", "expiresAt", "revoked", "access", "purpose", "canAttach", "deviceLimit", "token" ], "additionalProperties": false }, "AttachedDevice": { "type": "object", "properties": { "deviceId": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "Private child device credential. Returned only at enrollment/attachment; revoking the device invalidates it." } }, "required": [ "deviceId", "token" ], "additionalProperties": false }, "Enrollment": { "type": "object", "properties": { "token": { "type": "string" }, "expiresInSeconds": { "type": "integer", "const": 600 }, "expiresAt": { "type": "integer" } }, "required": [ "token", "expiresInSeconds", "expiresAt" ], "additionalProperties": false }, "Account": { "type": "object", "properties": { "workspace": { "type": "string" }, "principal": { "type": "object", "properties": { "id": { "type": "string", "const": "owner" }, "owner": { "type": "boolean", "const": true } }, "required": [ "id", "owner" ], "additionalProperties": false }, "deviceControlsEnabled": { "type": "boolean" }, "agentClients": { "type": "array", "items": { "type": "string" } }, "oauthClientRegistration": { "type": "boolean" } }, "required": [ "workspace", "principal", "deviceControlsEnabled", "agentClients", "oauthClientRegistration" ], "additionalProperties": false }, "HistoryExport": { "type": "object", "properties": { "format": { "type": "string", "const": "openlaunch.actions.v1" }, "exportedAt": { "type": "integer" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionExport" } } }, "required": [ "format", "exportedAt", "actions" ], "additionalProperties": false }, "BroadcastResult": { "type": "object", "properties": { "deviceId": { "type": "string", "format": "uuid" }, "action": { "$ref": "#/components/schemas/ActionReceipt" }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "deviceId" ], "additionalProperties": false }, "DeviceNext": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "deviceId": { "type": "string", "format": "uuid" }, "capability": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "const": "received" }, "createdAt": { "type": "integer" }, "expiresAt": { "type": "integer" }, "dispatchedAt": { "type": "integer" }, "accessPolicy": { "type": "string", "description": "Policy principal that authorized this action when queued; dispatch re-checks the live chain for that policy before delivering." }, "accessConstraints": { "type": "array", "items": { "type": "string" }, "description": "Constraint principals re-checked against their live policies at dispatch time." } }, "required": [ "id", "deviceId", "capability", "args", "status", "createdAt", "expiresAt", "dispatchedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "ManifestUpdate": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "grantsRevoked": { "type": "boolean" } }, "required": [ "ok", "grantsRevoked" ], "additionalProperties": false }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false }, "OAuthRevocation": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "providerCleanupPending": { "type": "boolean" } }, "required": [ "ok", "providerCleanupPending" ], "additionalProperties": false }, "OAuthRegistration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "principal": { "type": "string" }, "name": { "type": "string" }, "expiresAt": { "type": [ "integer", "null" ] }, "revoked": { "type": "boolean" }, "access": { "type": "string", "enum": [ "read", "act" ] }, "purpose": { "type": "string", "const": "oauth" }, "canAttach": { "type": "boolean", "const": false }, "deviceLimit": { "type": "integer", "const": 0 }, "oauth": { "type": "object", "properties": { "applicationId": { "type": "string" }, "clientId": { "type": "string" }, "redirectUris": { "type": "array", "items": { "type": "string", "format": "uri" } }, "public": { "type": "boolean" } }, "required": [ "applicationId", "clientId", "redirectUris", "public" ], "additionalProperties": false }, "clientSecret": { "type": "string", "description": "Returned only when the provider issued a secret; store securely and never log." } }, "required": [ "id", "principal", "name", "expiresAt", "revoked", "access", "purpose", "oauth" ], "additionalProperties": false } } }, "x-mcp": { "protocolVersion": "2026-07-28", "legacyHandshake": "MCP SDK Streamable HTTP initialization remains supported", "scopes": [ "openlaunch:read", "openlaunch:act" ], "note": "Scopes do not create device grants. The separate /docs-mcp endpoint is public read-only documentation." } }