{ "openapi": "3.1.0", "info": { "title": "RoboCloud Customer Open API v2.1", "version": "2.1.0", "description": "One account and one short-lived Open Session contract for password and Customer API Key login, plus an explicitly paired, device-signed RoboCloud Runner v14 control channel. Local actions are asynchronous and become authoritative only after the Runner confirms them." }, "servers": [ { "url": "https://shop.robocloud.store/api/open/v2" } ], "tags": [ { "name": "Authentication" }, { "name": "Account" }, { "name": "Services" }, { "name": "Active dynamic" }, { "name": "Runners" }, { "name": "Runner transport" } ], "x-error-code-catalog": { "authentication": [ "robocloud_auth_required", "robocloud_auth_invalid", "robocloud_session_expired", "robocloud_session_revoked", "robocloud_account_disabled", "robocloud_api_key_revoked", "robocloud_scope_required", "open_session_limit_reached" ], "ownership_and_lifecycle": [ "service_not_found", "robocloud_service_inactive", "package_inactive", "service_cancelled", "line_service_not_supported", "runner_not_found", "runner_operation_not_found", "robocloud_service_unavailable" ], "runner_pairing_and_authentication": [ "runner_pairing_not_found", "runner_pairing_invalid", "runner_pairing_expired", "runner_pairing_consumed", "runner_pairing_revoked", "runner_pairing_source_revoked", "runner_pairing_unsupported", "runner_pairing_limit_reached", "device_identity_conflict", "runner_auth_invalid", "runner_token_revoked", "runner_signature_invalid", "runner_request_replayed", "runner_version_unsupported" ], "runner_control": [ "runner_offline", "runner_capability_required", "runner_revision_conflict", "runner_observation_stale", "service_revision_conflict", "source_session_revoked", "runner_command_unsupported", "runner_node_invalid", "runner_operation_expired", "runner_limit_reached", "runner_lease_invalid", "runner_result_invalid", "runner_result_conflict", "runner_export_unavailable", "runner_projection_not_found" ], "idempotency_and_quotes": [ "idempotency_key_required", "idempotency_key_reused", "idempotency_not_supported", "quote_required", "quote_changed", "line_quote_changed", "balance_confirmation_required" ], "commerce_and_capacity": [ "insufficient_balance", "payg_minimum_balance_required", "payg_not_available", "payg_rate_unavailable", "payg_service_exists", "line_limit_reached", "line_operation_running", "manual_rotation_daily_limit" ], "availability": [ "request_too_large", "robocloud_upstream_unavailable", "robocloud_rate_limited", "database_busy" ] }, "x-scope-catalog": [ "account.read", "wallet.read", "plans.read", "services.read", "connection.read", "configuration.read", "nodes.read", "usage.read", "active_dynamic.read", "active_dynamic.control", "payg.open", "runner.read", "runner.pair", "runner.control" ], "x-minimum-runner-version": "14.0.0", "paths": { "/auth/sessions": { "post": { "operationId": "createOpenSession", "summary": "Exchange an account password or Customer API Key for an Open Session", "description": "The returned secret is shown once and is the only credential accepted by v2 business routes. Idempotency-Key is deliberately not accepted. A legacy read-only API Key succeeds with a truthful limited capability set.", "security": [ {}, { "CustomerApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PasswordSessionRequest" }, { "$ref": "#/components/schemas/ApiKeySessionRequest" } ] } } } }, "responses": { "201": { "description": "Session created", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/session": { "get": { "operationId": "getOpenSession", "summary": "Read the current Open Session", "security": [ { "OpenSession": [] } ], "x-required-scopes": [], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/auth/session/logout": { "post": { "operationId": "logoutOpenSession", "summary": "Revoke only the current Open Session", "security": [ { "OpenSession": [] } ], "x-required-scopes": [], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/me": { "get": { "operationId": "getIdentity", "summary": "Read the account identity", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "account.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/wallet": { "get": { "operationId": "getWallet", "summary": "Read the authoritative integer-minor-unit wallet", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "wallet.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/plans": { "get": { "operationId": "listPlans", "summary": "List prepaid and PAYG plans", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "plans.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/plans/{sku}": { "parameters": [ { "name": "sku", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "operationId": "getPlan", "summary": "Read one plan", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "plans.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/services": { "get": { "operationId": "listServices", "summary": "List every service owned by the account", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "services.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/services/{service_id}/connection": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getServiceConnection", "summary": "Read safe connection metadata", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "connection.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "202": { "description": "Connection is still pending", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionResponse" } } } } }, "description": "Never returns a stable subscription URL or node credentials." } }, "/services/{service_id}/configuration": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getServiceConfiguration", "summary": "Read the authenticated Clash configuration payload", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "configuration.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfigurationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "New credentials require configuration.read. During the documented v2.0 migration window only, an already-existing Key with connection.read may retain compatibility; this does not grant any Runner scope.", "parameters": [ { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "clash" ], "default": "clash" } } ] } }, "/services/{service_id}/nodes": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "listServiceNodes", "summary": "Read safe node metadata", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "nodes.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "202": { "description": "Node projection is still pending", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } } } } }, "/services/{service_id}/usage": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getServiceUsage", "summary": "Read traffic, billing, and wallet usage", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "usage.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/payg/services": { "post": { "operationId": "createPaygService", "summary": "Open an independently metered PAYG service", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "payg.open" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaygServiceCreationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Idempotent replay of an existing service", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaygServiceCreationResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaygServiceRequest" } } } } } }, "/operations/{operation_id}": { "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getOperation", "summary": "Read a service operation", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "services.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerServiceOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/runner-pairings": { "post": { "operationId": "createRunnerPairing", "summary": "Create a five-minute, one-time Runner pairing", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.pair" ], "responses": { "201": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerPairingSecretResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "pairingSecret is returned exactly once and must never be placed in a URL, log, screenshot, or telemetry event. Creating a pairing does not create a Runner.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRunnerPairingRequest" } } } } } }, "/runner-pairings/{pairing_id}": { "parameters": [ { "name": "pairing_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getRunnerPairing", "summary": "Read pairing status without returning its secret", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.pair" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerPairingStatusResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/runners/pair": { "post": { "operationId": "pairRunner", "summary": "Consume a pairing secret and register an Ed25519 Runner identity", "description": "Public only in the sense that it does not accept Open Session authentication. The request must contain a live one-time pairing secret and proof that the Runner holds the private key corresponding to devicePublicKey. Runner v14.0.0 or newer is required.", "security": [ {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairRunnerRequest" } } } }, "responses": { "201": { "description": "Runner paired", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PairRunnerResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "410": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "426": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/runners": { "get": { "operationId": "listRunners", "summary": "List paired Runners owned by the current account", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerListResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/runners/{runner_id}": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getRunner", "summary": "Read one account-owned Runner", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "operationId": "unpairRunner", "summary": "Revoke the Runner Token and unpair the device", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.pair" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerUnpairResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/runners/{runner_id}/services/{service_id}/select": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "selectRunnerService", "summary": "Queue service.select on a paired Runner", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Idempotent replay of the existing Runner operation", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerSelectServiceRequest" } } } } } }, "/runners/{runner_id}/node-tests": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "testRunnerNodes", "summary": "Queue nodes.test on a paired Runner", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Idempotent replay of the existing Runner operation", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerNodeTestRequest" } } } } } }, "/runners/{runner_id}/node-starts": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "startRunnerNodes", "summary": "Queue node.start for an allowlisted node batch on a paired Runner", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Idempotent replay of the existing Runner operation", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerNodeActionRequest" } } } } } }, "/runners/{runner_id}/node-stops": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "stopRunnerNodes", "summary": "Queue node.stop for an allowlisted node batch on a paired Runner", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Idempotent replay of the existing Runner operation", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerNodeActionRequest" } } } } } }, "/runners/{runner_id}/refreshes": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "refreshRunner", "summary": "Queue runner.refresh on a paired Runner", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "200": { "description": "Idempotent replay of the existing Runner operation", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerRefreshRequest" } } } } } }, "/runners/{runner_id}/exports": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "serviceId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getRunnerExports", "summary": "Read only Runner-confirmed local egress projections", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerExportsResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "Every returned endpoint has networkScope=runner_local. A loopback host is usable only by software running on that Runner device; it is never a cloud-reachable proxy." } }, "/runners/{runner_id}/operations/{operation_id}": { "parameters": [ { "name": "runner_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getRunnerOperation", "summary": "Read the real queued/running/terminal state of a Runner operation", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "runner.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/runner/heartbeat": { "post": { "operationId": "runnerHeartbeat", "summary": "Update the bounded current Runner state", "description": "Sign the exact UTF-8 request body with the paired Ed25519 device key. The canonical bytes are METHOD, normalized absolute path, X-RoboCloud-Runner-Timestamp, X-RoboCloud-Runner-Nonce, and lowercase SHA-256 hex of the body, joined with LF. The signature is base64url without padding. Runner Token alone is not sufficient: timestamp, nonce, and signature are all required.", "security": [ { "RunnerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RunnerTimestamp" }, { "$ref": "#/components/parameters/RunnerNonce" }, { "$ref": "#/components/parameters/RunnerSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerHeartbeatRequest" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerHeartbeatResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "426": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-runner-signature-canonical": "METHOD\\nNORMALIZED_ABSOLUTE_PATH\\nX-ROBOCLOUD-RUNNER-TIMESTAMP\\nX-ROBOCLOUD-RUNNER-NONCE\\nSHA256_HEX(EXACT_BODY_BYTES)" } }, "/runner/commands/claim": { "post": { "operationId": "claimRunnerCommands", "summary": "Immediately claim ready commands with finite leases (never long-poll)", "description": "Sign the exact UTF-8 request body with the paired Ed25519 device key. The canonical bytes are METHOD, normalized absolute path, X-RoboCloud-Runner-Timestamp, X-RoboCloud-Runner-Nonce, and lowercase SHA-256 hex of the body, joined with LF. The signature is base64url without padding. Runner Token alone is not sufficient: timestamp, nonce, and signature are all required.", "security": [ { "RunnerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RunnerTimestamp" }, { "$ref": "#/components/parameters/RunnerNonce" }, { "$ref": "#/components/parameters/RunnerSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerCommandClaimRequest" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerCommandClaimResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-runner-signature-canonical": "METHOD\\nNORMALIZED_ABSOLUTE_PATH\\nX-ROBOCLOUD-RUNNER-TIMESTAMP\\nX-ROBOCLOUD-RUNNER-NONCE\\nSHA256_HEX(EXACT_BODY_BYTES)" } }, "/runner/operations/{operation_id}/results": { "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "completeRunnerOperation", "summary": "Confirm a leased command result without replaying local side effects", "description": "Sign the exact UTF-8 request body with the paired Ed25519 device key. The canonical bytes are METHOD, normalized absolute path, X-RoboCloud-Runner-Timestamp, X-RoboCloud-Runner-Nonce, and lowercase SHA-256 hex of the body, joined with LF. The signature is base64url without padding. Runner Token alone is not sufficient: timestamp, nonce, and signature are all required.", "security": [ { "RunnerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RunnerTimestamp" }, { "$ref": "#/components/parameters/RunnerNonce" }, { "$ref": "#/components/parameters/RunnerSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResultRequest" } } } }, "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunnerOperationResultResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-runner-signature-canonical": "METHOD\\nNORMALIZED_ABSOLUTE_PATH\\nX-ROBOCLOUD-RUNNER-TIMESTAMP\\nX-ROBOCLOUD-RUNNER-NONCE\\nSHA256_HEX(EXACT_BODY_BYTES)" } }, "/services/{service_id}/active-dynamic/lines": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "listActiveDynamicLines", "summary": "Read active-dynamic line state", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/services/{service_id}/active-dynamic/control-state": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getActiveDynamicControlState", "summary": "Read the schema-v1 active-dynamic control projection", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicServiceControl" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "description": "A stable customer projection. Operation states are normalized to the closed schema-v1 status set; internal task, lease, retry, Gateway, and observation states are never returned." } }, "/services/{service_id}/active-dynamic/regions": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "listActiveDynamicRegions", "summary": "Read available egress regions", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/services/{service_id}/active-dynamic/region-operations": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "changeActiveDynamicRegion", "summary": "Queue an account-owned region change", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveDynamicOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionOperationRequest" } } } } } }, "/services/{service_id}/active-dynamic/rotation-policy": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "put": { "operationId": "setActiveDynamicRotationPolicy", "summary": "Queue a rotation-policy change", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveDynamicOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationPolicyRequest" } } } } } }, "/services/{service_id}/active-dynamic/control-operations/{operation_id}": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getActiveDynamicControlOperation", "summary": "Read region/policy operation progress", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveDynamicOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/services/{service_id}/active-dynamic/rotation-operations": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "rotateActiveDynamicLines", "summary": "Queue a manual rotation", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualRotationOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualRotationRequest" } } } } } }, "/services/{service_id}/active-dynamic/rotation-operations/{operation_id}": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getActiveDynamicRotationOperation", "summary": "Read manual-rotation progress", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualRotationOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/services/{service_id}/active-dynamic/line-operation-quote": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "quoteActiveDynamicLines", "summary": "Quote additional active-dynamic lines", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "name": "quantity", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1 } } ] } }, "/services/{service_id}/active-dynamic/line-operations": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "post": { "operationId": "addActiveDynamicLines", "summary": "Queue quoted additional lines", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.control", "payg.open" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveDynamicOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineOperationRequest" } } } } } }, "/services/{service_id}/active-dynamic/line-operations/{operation_id}": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "get": { "operationId": "getActiveDynamicLineOperation", "summary": "Read line-operation progress", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.read" ], "responses": { "200": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveDynamicOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/services/{service_id}/active-dynamic/lines/{line_id}": { "parameters": [ { "name": "service_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } }, { "name": "line_id", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 64 } } ], "delete": { "operationId": "removeActiveDynamicLine", "summary": "Queue removal of one active-dynamic line", "security": [ { "OpenSession": [] } ], "x-required-scopes": [ "active_dynamic.control" ], "responses": { "202": { "description": "Successful response", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveDynamicOperationResponse" } } } }, "400": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "402": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Request was rejected", "headers": { "X-Request-ID": { "description": "Request correlation identifier.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } } }, "components": { "securitySchemes": { "OpenSession": { "type": "http", "scheme": "bearer", "bearerFormat": "opaque RoboCloud Open Session", "description": "Required by every v2 business route. Browser cookies and raw Customer API Keys are rejected." }, "CustomerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "rbl_live_*", "description": "Accepted only while creating an Open Session." }, "RunnerAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Use `Authorization: Runner rbl_run_REPLACE_WITH_RUNNER_TOKEN`. This Runner-specific token is returned once at pairing and cannot be used as an Open Session. Every request must also carry a valid Ed25519 signature." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, "RunnerTimestamp": { "name": "X-RoboCloud-Runner-Timestamp", "in": "header", "required": true, "description": "Unix seconds covered by the Ed25519 signature and freshness window.", "schema": { "type": "string", "pattern": "^[0-9]{10,13}$" } }, "RunnerNonce": { "name": "X-RoboCloud-Runner-Nonce", "in": "header", "required": true, "description": "Unique 16-128 character nonce; reuse within the retention window is rejected.", "schema": { "type": "string", "minLength": 16, "maxLength": 128 } }, "RunnerSignature": { "name": "X-RoboCloud-Runner-Signature", "in": "header", "required": true, "description": "Sign the exact UTF-8 request body with the paired Ed25519 device key. The canonical bytes are METHOD, normalized absolute path, X-RoboCloud-Runner-Timestamp, X-RoboCloud-Runner-Nonce, and lowercase SHA-256 hex of the body, joined with LF. The signature is base64url without padding. Runner Token alone is not sufficient: timestamp, nonce, and signature are all required.", "schema": { "type": "string", "minLength": 80, "maxLength": 120 } } }, "schemas": { "DataResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": [ "object", "array" ] } } }, "CustomerServiceOperation": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "status", "progress", "serviceId", "requestId", "lastErrorCode", "lastError", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "maxLength": 64 }, "type": { "type": [ "string", "null" ], "maxLength": 32 }, "status": { "type": "string", "maxLength": 24 }, "progress": { "type": "integer", "minimum": 0, "maximum": 100 }, "serviceId": { "type": [ "string", "null" ], "maxLength": 64 }, "requestId": { "type": [ "string", "null" ], "maxLength": 64, "description": "The first accepted request's correlation ID. It remains stable on idempotent replay; null is reserved for historical or background-created rows." }, "lastErrorCode": { "type": [ "string", "null" ], "maxLength": 96 }, "lastError": { "type": [ "string", "null" ], "maxLength": 500 }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PublicOperation": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "status", "requestedCount", "completedCount", "succeededCount", "failedCount", "lastErrorCode", "lastError", "updatedAt" ], "properties": { "id": { "type": "string", "maxLength": 128 }, "type": { "type": [ "string", "null" ], "maxLength": 32 }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "partially_failed", "failed", "superseded" ] }, "requestedCount": { "type": "integer", "minimum": 0 }, "completedCount": { "type": "integer", "minimum": 0 }, "succeededCount": { "type": "integer", "minimum": 0 }, "failedCount": { "type": "integer", "minimum": 0 }, "lastErrorCode": { "type": [ "string", "null" ], "maxLength": 96 }, "lastError": { "type": [ "string", "null" ], "maxLength": 500 }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "PublicServiceControl": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "serviceId", "serviceStatus", "desiredRegionCode", "effectiveRegionCode", "availableRegions", "rotationPolicy", "manualRotation", "lines", "operations", "allowedActions", "updatedAt" ], "properties": { "schemaVersion": { "const": 1 }, "serviceId": { "type": "string", "maxLength": 64 }, "serviceStatus": { "type": "string" }, "desiredRegionCode": { "type": [ "string", "null" ], "maxLength": 16 }, "effectiveRegionCode": { "type": [ "string", "null" ], "maxLength": 16 }, "availableRegions": { "type": "array", "items": { "type": "object" } }, "rotationPolicy": { "type": [ "object", "null" ] }, "manualRotation": { "type": [ "object", "null" ] }, "lines": { "type": "array", "items": { "type": "object" } }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOperation" } }, "allowedActions": { "type": "array", "items": { "type": "object" } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "CustomerServiceOperationResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/CustomerServiceOperation" } } }, "ActiveDynamicOperationResponse": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "data" ], "properties": { "schemaVersion": { "const": 1 }, "data": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/PublicOperation" } }, "additionalProperties": true } } }, "ManualRotationOperationResponse": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "data" ], "properties": { "schemaVersion": { "const": 1 }, "data": { "type": "object", "required": [ "operation" ], "properties": { "operation": { "$ref": "#/components/schemas/PublicOperation" } }, "additionalProperties": true } } }, "PaygServiceCreationResponse": { "type": "object", "additionalProperties": false, "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "service", "operation", "wallet" ], "properties": { "service": { "type": [ "object", "null" ], "additionalProperties": true }, "operation": { "$ref": "#/components/schemas/CustomerServiceOperation" }, "wallet": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "requestId", "details" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable code; see x-error-code-catalog for the common v2 contract.", "examples": [ "robocloud_scope_required", "service_not_found", "idempotency_key_reused" ] }, "message": { "type": "string" }, "requestId": { "type": [ "string", "null" ] }, "details": { "type": "object", "additionalProperties": true } } } } }, "ScopeName": { "type": "string", "enum": [ "account.read", "wallet.read", "plans.read", "services.read", "connection.read", "configuration.read", "nodes.read", "usage.read", "active_dynamic.read", "active_dynamic.control", "payg.open", "runner.read", "runner.pair", "runner.control" ] }, "SessionCapabilities": { "type": "object", "additionalProperties": false, "required": [ "accountRead", "walletRead", "plansRead", "servicesRead", "connectionRead", "configurationRead", "nodesRead", "usageRead", "activeDynamicRead", "activeDynamicControl", "paygOpen", "runnerRead", "runnerPair", "runnerControl" ], "properties": { "accountRead": { "type": "boolean" }, "walletRead": { "type": "boolean" }, "plansRead": { "type": "boolean" }, "servicesRead": { "type": "boolean" }, "connectionRead": { "type": "boolean" }, "configurationRead": { "type": "boolean" }, "nodesRead": { "type": "boolean" }, "usageRead": { "type": "boolean" }, "activeDynamicRead": { "type": "boolean" }, "activeDynamicControl": { "type": "boolean" }, "paygOpen": { "type": "boolean" }, "runnerRead": { "type": "boolean" }, "runnerPair": { "type": "boolean" }, "runnerControl": { "type": "boolean" } } }, "PasswordSessionRequest": { "type": "object", "additionalProperties": false, "required": [ "auth_method", "email", "password" ], "properties": { "auth_method": { "const": "account_password" }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "password": { "type": "string", "minLength": 8, "maxLength": 128, "writeOnly": true }, "device_summary": { "type": "string", "maxLength": 160 }, "required_scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeName" }, "uniqueItems": true } } }, "ApiKeySessionRequest": { "type": "object", "additionalProperties": false, "required": [ "auth_method" ], "properties": { "auth_method": { "const": "api_key" }, "device_summary": { "type": "string", "maxLength": 160 }, "required_scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeName" }, "uniqueItems": true } } }, "SessionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "sessionToken", "tokenType", "account", "expiresAt", "effectiveScopes", "capabilities", "integrationStatus", "missingRequiredScopes", "requestedScopes", "requestedScopesSatisfied", "missingRequestedScopes" ], "properties": { "sessionToken": { "type": "string", "writeOnly": true }, "tokenType": { "const": "Bearer" }, "account": { "type": "object", "additionalProperties": true }, "expiresAt": { "type": "string", "format": "date-time" }, "effectiveScopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeName" }, "uniqueItems": true }, "capabilities": { "$ref": "#/components/schemas/SessionCapabilities" }, "integrationStatus": { "type": "string", "enum": [ "full", "limited" ] }, "missingRequiredScopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeName" }, "uniqueItems": true }, "requestedScopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeName" }, "uniqueItems": true }, "requestedScopesSatisfied": { "type": "boolean" }, "missingRequestedScopes": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeName" }, "uniqueItems": true } } } } }, "WalletResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "wallet": { "type": "object", "required": [ "balanceMinor", "currency", "formatted", "updatedAt" ], "properties": { "balanceMinor": { "type": "integer", "format": "int64" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "formatted": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } } } } } }, "ConnectionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "serviceId", "revision", "status", "stale", "subscriptionReady", "nodeCount" ], "properties": { "serviceId": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "status": { "type": "string" }, "stale": { "type": "boolean" }, "subscriptionReady": { "type": "boolean" }, "nodeCount": { "type": "integer", "minimum": 0 }, "configurationEndpoint": { "type": [ "string", "null" ] } } } } }, "ConfigurationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "serviceId", "format", "revision", "stale", "configuration" ], "properties": { "serviceId": { "type": "string" }, "format": { "const": "clash" }, "revision": { "type": "integer", "minimum": 1 }, "stale": { "type": "boolean" }, "configuration": { "type": [ "object", "string" ], "description": "Sensitive authenticated configuration payload; never a stable URL." } } } } }, "RunnerCapabilityName": { "type": "string", "enum": [ "service.select", "service.status", "nodes.read", "nodes.test", "node.start", "node.stop", "exports.read", "runner.refresh" ], "description": "Closed command allowlist. Shell, script, arbitrary URL, and free-form command names are forbidden." }, "CreateRunnerPairingRequest": { "type": "object", "additionalProperties": false, "properties": { "displayName": { "type": "string", "maxLength": 120 }, "capabilities": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/RunnerCapabilityName" } } } }, "RunnerPairingSecretResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "pairingId", "pairingSecret", "expiresAt", "pairingEndpoint", "minimumRunnerVersion" ], "properties": { "pairingId": { "type": "string" }, "pairingSecret": { "type": "string", "writeOnly": true, "description": "One-time secret returned only by this response." }, "expiresAt": { "type": "string", "format": "date-time" }, "pairingEndpoint": { "const": "/api/open/v2/runners/pair" }, "minimumRunnerVersion": { "const": "14.0.0" } } } } }, "RunnerPairingStatusResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "pairingId", "status", "expiresAt", "runnerId", "name", "consumedAt", "createdAt" ], "properties": { "pairingId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "paired", "expired", "cancelled" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "runnerId": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "consumedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } } } }, "PairRunnerRequest": { "type": "object", "additionalProperties": false, "required": [ "pairingId", "pairingSecret", "device", "proof" ], "properties": { "pairingId": { "type": "string", "maxLength": 64 }, "pairingSecret": { "type": "string", "writeOnly": true, "maxLength": 192 }, "proof": { "type": "object", "additionalProperties": false, "required": [ "timestamp", "nonce", "signature" ], "properties": { "timestamp": { "type": "integer", "format": "int64" }, "nonce": { "type": "string", "minLength": 16, "maxLength": 128 }, "signature": { "type": "string", "writeOnly": true, "description": "Base64url Ed25519 signature over pair, pairingId, device.id, proof.timestamp, and proof.nonce joined with LF." } } }, "device": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "platform", "version", "capabilities", "publicKey" ], "properties": { "id": { "type": "string", "maxLength": 128, "description": "Stable display/deduplication identifier; never the trust root." }, "name": { "type": [ "string", "null" ], "maxLength": 120 }, "platform": { "type": "string", "maxLength": 80 }, "version": { "type": "string", "pattern": "^v?[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$" }, "capabilities": { "type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/RunnerCapabilityName" } }, "publicKey": { "type": "string", "description": "Base64url, no-padding raw 32-byte Ed25519 public key." } } } } }, "PairRunnerResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "runnerId", "accountId", "runnerToken", "tokenType", "heartbeatIntervalSeconds", "offlineAfterSeconds" ], "properties": { "runnerId": { "type": "string" }, "accountId": { "type": "string" }, "runnerToken": { "type": "string", "pattern": "^rbl_run_", "writeOnly": true, "description": "Returned once; store in an OS credential store." }, "tokenType": { "const": "Runner" }, "heartbeatIntervalSeconds": { "type": "integer", "minimum": 1, "maximum": 300 }, "offlineAfterSeconds": { "type": "integer", "minimum": 5, "maximum": 900 } } } } }, "Runner": { "type": "object", "additionalProperties": false, "required": [ "runnerId", "deviceId", "deviceKeyFingerprint", "name", "version", "platform", "capabilities", "status", "online", "lastSeenAt", "stateRevision", "selectedServiceId", "createdAt", "revokedAt" ], "properties": { "runnerId": { "type": "string" }, "deviceId": { "type": "string" }, "deviceKeyFingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "name": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "platform": { "type": "string" }, "capabilities": { "type": "array", "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/RunnerCapabilityName" } }, "status": { "type": "string", "enum": [ "online", "offline", "revoked" ] }, "online": { "type": "boolean" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "stateRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "selectedServiceId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "RunnerResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Runner" } } }, "RunnerListResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "runners", "items" ], "properties": { "runners": { "type": "array", "items": { "$ref": "#/components/schemas/Runner" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Runner" } } } } } }, "RunnerUnpairResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "runnerId", "revoked" ], "properties": { "runnerId": { "type": "string" }, "revoked": { "const": true } } } } }, "RunnerSelectServiceRequest": { "type": "object", "additionalProperties": false, "required": [ "expectedServiceRevision", "expectedRunnerRevision" ], "properties": { "expectedServiceRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "expectedRunnerRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, "RunnerNodeTestRequest": { "type": "object", "additionalProperties": false, "required": [ "serviceId", "nodeIds", "expectedServiceRevision", "expectedRunnerRevision" ], "properties": { "serviceId": { "type": "string", "maxLength": 64 }, "nodeIds": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "maxLength": 128 } }, "expectedServiceRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "expectedRunnerRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, "RunnerNodeActionRequest": { "type": "object", "additionalProperties": false, "required": [ "serviceId", "nodeIds", "expectedServiceRevision", "expectedRunnerRevision" ], "properties": { "serviceId": { "type": "string", "maxLength": 64 }, "nodeIds": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "description": "Every ID must exist in the service revision's cloud-provided node allowlist.", "items": { "type": "string", "maxLength": 128 } }, "expectedServiceRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "expectedRunnerRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, "RunnerRefreshRequest": { "type": "object", "additionalProperties": false, "required": [ "serviceId", "expectedServiceRevision", "expectedRunnerRevision" ], "properties": { "serviceId": { "type": "string", "maxLength": 64 }, "expectedServiceRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "expectedRunnerRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 } } }, "RunnerOperation": { "type": "object", "additionalProperties": false, "required": [ "operationId", "requestId", "runnerId", "serviceId", "type", "status", "expectedServiceRevision", "expectedRunnerRevision", "deadline", "createdAt", "completedAt" ], "properties": { "operationId": { "type": "string" }, "requestId": { "type": "string", "description": "Stable request identifier captured when the asynchronous operation was submitted." }, "runnerId": { "type": "string" }, "serviceId": { "type": [ "string", "null" ] }, "type": { "$ref": "#/components/schemas/RunnerCapabilityName" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "expired", "cancelled" ] }, "expectedServiceRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "expectedRunnerRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "deadline": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "result": { "type": [ "object", "null" ], "additionalProperties": true }, "error": { "oneOf": [ { "$ref": "#/components/schemas/RunnerCommandError" }, { "type": "null" } ] } } }, "RunnerOperationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RunnerOperation" } } }, "RunnerExport": { "type": "object", "additionalProperties": false, "required": [ "id", "nodeId", "name", "protocol", "host", "port", "networkScope", "confirmed" ], "properties": { "id": { "type": "string" }, "nodeId": { "type": "string" }, "name": { "type": "string" }, "protocol": { "type": "string", "enum": [ "http", "socks5", "mixed" ] }, "host": { "type": "string", "enum": [ "127.0.0.1", "::1" ] }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "networkScope": { "const": "runner_local", "description": "Reachable only from the paired Runner device, never from the cloud caller by implication." }, "confirmed": { "const": true, "description": "Public projections contain only endpoints that the Runner confirmed locally reachable." } } }, "RunnerHeartbeatExport": { "type": "object", "additionalProperties": false, "required": [ "id", "nodeId", "name", "protocol", "host", "port", "networkScope", "confirmed" ], "properties": { "id": { "type": "string", "maxLength": 128 }, "nodeId": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 200 }, "protocol": { "type": "string", "enum": [ "http", "socks5", "mixed" ] }, "host": { "type": "string", "enum": [ "127.0.0.1", "::1" ] }, "port": { "type": "integer", "minimum": 1, "maximum": 65535 }, "networkScope": { "const": "runner_local" }, "confirmed": { "type": "boolean", "description": "false is accepted on transport for diagnosis; public exports filter it out." } } }, "RunnerExportsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "runnerId", "serviceId", "stateRevision", "serviceRevision", "networkScope", "exports", "observedAt" ], "properties": { "runnerId": { "type": "string" }, "serviceId": { "type": "string" }, "stateRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "serviceRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "networkScope": { "const": "runner_local" }, "exports": { "type": "array", "items": { "$ref": "#/components/schemas/RunnerExport" } }, "observedAt": { "type": "string", "format": "date-time" } } } } }, "RunnerHeartbeatRequest": { "type": "object", "additionalProperties": false, "dependentRequired": { "selectedServiceId": [ "selectedServiceRevision" ] }, "required": [ "deviceId", "accountId", "version", "platform", "capabilities", "stateRevision", "status", "exports", "observedAt" ], "properties": { "deviceId": { "type": "string", "maxLength": 128 }, "accountId": { "type": "string", "maxLength": 128 }, "version": { "type": "string" }, "platform": { "type": "string", "maxLength": 80 }, "capabilities": { "type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": { "$ref": "#/components/schemas/RunnerCapabilityName" } }, "stateRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "status": { "type": "string", "enum": [ "idle", "running", "degraded", "stopped", "error" ] }, "selectedServiceId": { "type": "string", "maxLength": 128 }, "selectedServiceRevision": { "type": "integer", "minimum": 1, "maximum": 9223372036854775807, "description": "The service configuration revision actually applied locally by this Runner; never inferred from the cloud's current revision." }, "exports": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/RunnerHeartbeatExport" } }, "observedAt": { "type": "string", "format": "date-time" } } }, "RunnerHeartbeatResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "serverTime", "nextHeartbeatInSeconds", "runnerStatus" ], "properties": { "serverTime": { "type": "string", "format": "date-time" }, "nextHeartbeatInSeconds": { "type": "integer", "minimum": 1, "maximum": 300 }, "runnerStatus": { "type": "string", "enum": [ "online", "revoked", "disabled" ] } } } } }, "RunnerCommandClaimRequest": { "type": "object", "additionalProperties": false, "required": [ "limit" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 1 } } }, "RunnerCommand": { "type": "object", "additionalProperties": false, "required": [ "operationId", "leaseToken", "type", "serviceId", "expectedServiceRevision", "expectedRunnerRevision", "deadline", "payload" ], "properties": { "operationId": { "type": "string" }, "leaseToken": { "type": "string", "writeOnly": true }, "type": { "$ref": "#/components/schemas/RunnerCapabilityName" }, "serviceId": { "type": [ "string", "null" ] }, "expectedServiceRevision": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9223372036854775807 }, "expectedRunnerRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "deadline": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "additionalProperties": true, "description": "Command-specific payload; sensitive configuration appears only here over the authenticated Runner channel and must not be persisted or logged by the cloud command row." } } }, "RunnerCommandClaimResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "commands" ], "properties": { "commands": { "type": "array", "maxItems": 1, "items": { "$ref": "#/components/schemas/RunnerCommand" } } } } } }, "RunnerCommandError": { "type": "object", "additionalProperties": false, "required": [ "code", "message" ], "properties": { "code": { "type": "string", "maxLength": 80 }, "message": { "type": "string", "maxLength": 300 }, "details": { "type": "object", "additionalProperties": true, "description": "Sanitized details only; secrets, configuration, tokens, and credentials are forbidden." } } }, "RunnerOperationResultRequest": { "type": "object", "additionalProperties": false, "required": [ "leaseToken", "status", "stateRevision", "result" ], "properties": { "leaseToken": { "type": "string", "writeOnly": true }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "stateRevision": { "type": "integer", "minimum": 0, "maximum": 9223372036854775807 }, "result": { "type": [ "object", "null" ], "additionalProperties": true }, "error": { "oneOf": [ { "$ref": "#/components/schemas/RunnerCommandError" }, { "type": "null" } ] } } }, "RunnerOperationResultResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "operationId", "status", "completedAt" ], "properties": { "operationId": { "type": "string" }, "status": { "type": "string", "enum": [ "succeeded", "failed" ] }, "completedAt": { "type": "string", "format": "date-time" } } } } }, "RegionOperationRequest": { "type": "object", "additionalProperties": false, "required": [ "targetRegionCode" ], "properties": { "targetRegionCode": { "type": "string", "maxLength": 16 } } }, "RotationPolicyRequest": { "type": "object", "additionalProperties": false, "required": [ "rotationMode", "intervalSeconds" ], "properties": { "rotationMode": { "type": "string", "enum": [ "disabled", "interval", "manual" ] }, "intervalSeconds": { "type": "integer", "minimum": 0 } } }, "ManualRotationRequest": { "type": "object", "additionalProperties": false, "required": [ "lineIds" ], "properties": { "lineIds": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "maxLength": 64 } } } }, "PaygServiceRequest": { "type": "object", "additionalProperties": false, "required": [ "sku", "confirmAutomaticDebit", "expectedPlanVersion", "expectedBasePriceMinorPerGb", "expectedCurrency" ], "properties": { "sku": { "type": "string", "maxLength": 128 }, "confirmAutomaticDebit": { "const": true }, "expectedPlanVersion": { "type": "integer", "minimum": 1 }, "expectedBasePriceMinorPerGb": { "type": "integer", "minimum": 0 }, "expectedCurrency": { "type": "string", "minLength": 3, "maxLength": 3 } } }, "LineOperationRequest": { "type": "object", "additionalProperties": false, "required": [ "quantity", "maxAmountMinor", "useBalance" ], "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 50 }, "maxAmountMinor": { "type": "integer", "minimum": 0 }, "useBalance": { "type": "boolean" } } } } } }