{ "components": { "examples": { "CHANNEL_DIRECTORY_RATE_LIMITED": { "summary": "CHANNEL_DIRECTORY_RATE_LIMITED", "value": { "error": { "code": "CHANNEL_DIRECTORY_RATE_LIMITED", "message": "Too many requests. Wait for Retry-After and try again." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "DEPENDENCY_UNAVAILABLE": { "summary": "DEPENDENCY_UNAVAILABLE", "value": { "error": { "code": "DEPENDENCY_UNAVAILABLE", "message": "A required dependency is unavailable." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "FORBIDDEN": { "summary": "FORBIDDEN", "value": { "error": { "code": "FORBIDDEN", "message": "The caller is not allowed to perform this operation." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "INTERNAL_ERROR": { "summary": "INTERNAL_ERROR", "value": { "error": { "code": "INTERNAL_ERROR", "message": "The platform request could not be completed." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "INVALID_REQUEST": { "summary": "INVALID_REQUEST", "value": { "error": { "code": "INVALID_REQUEST", "message": "The request does not match the operation contract." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "MODEL_DISCOVERY_RATE_LIMITED": { "summary": "MODEL_DISCOVERY_RATE_LIMITED", "value": { "error": { "code": "MODEL_DISCOVERY_RATE_LIMITED", "message": "Too many requests. Wait for Retry-After and try again." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "NATIVE_ADMIN_RETURN_RATE_LIMITED": { "summary": "NATIVE_ADMIN_RETURN_RATE_LIMITED", "value": { "error": { "code": "NATIVE_ADMIN_RETURN_RATE_LIMITED", "message": "Too many requests. Wait for Retry-After and try again." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "NOT_FOUND": { "summary": "NOT_FOUND", "value": { "error": { "code": "NOT_FOUND", "message": "The requested platform resource was not found." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "NOT_IMPLEMENTED": { "summary": "NOT_IMPLEMENTED", "value": { "error": { "code": "NOT_IMPLEMENTED", "message": "The selected Driver does not support this operation." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "PAYLOAD_TOO_LARGE": { "summary": "PAYLOAD_TOO_LARGE", "value": { "error": { "code": "PAYLOAD_TOO_LARGE", "message": "The request body exceeds the permitted size." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "PLUGIN_DISCOVERY_RATE_LIMITED": { "summary": "PLUGIN_DISCOVERY_RATE_LIMITED", "value": { "error": { "code": "PLUGIN_DISCOVERY_RATE_LIMITED", "message": "Too many requests. Wait for Retry-After and try again." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "RATE_LIMITED": { "summary": "RATE_LIMITED", "value": { "error": { "code": "RATE_LIMITED", "message": "Too many requests. Wait for Retry-After and try again." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "RESOURCE_CONFLICT": { "summary": "RESOURCE_CONFLICT", "value": { "error": { "code": "RESOURCE_CONFLICT", "message": "The requested operation conflicts with the current resource state." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "RUNTIME_LOGS_RATE_LIMITED": { "summary": "RUNTIME_LOGS_RATE_LIMITED", "value": { "error": { "code": "RUNTIME_LOGS_RATE_LIMITED", "message": "Too many requests. Wait for Retry-After and try again." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "RUNTIME_LOGS_TIMEOUT": { "summary": "RUNTIME_LOGS_TIMEOUT", "value": { "error": { "code": "RUNTIME_LOGS_TIMEOUT", "message": "The runtime status or log read timed out." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "UNAUTHENTICATED": { "summary": "UNAUTHENTICATED", "value": { "error": { "code": "UNAUTHENTICATED", "message": "The caller did not provide valid credentials." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "UNSUPPORTED_MEDIA_TYPE": { "summary": "UNSUPPORTED_MEDIA_TYPE", "value": { "error": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "The request content type is not supported." }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schemas": { "def-0": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" }, { "type": "null" }, { "items": { "$ref": "#/components/schemas/def-0" }, "type": "array" }, { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "properties": {}, "type": "object" } ], "title": "SafeJsonValue" }, "def-1": { "additionalProperties": false, "properties": { "id": { "minLength": 1, "type": "string" }, "implementation": { "minLength": 1, "type": "string" } }, "required": ["id", "implementation"], "title": "PluginDriverIdentity", "type": "object" }, "def-10": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "cursor": { "anyOf": [{ "maxLength": 2048, "type": "string" }, { "type": "null" }] }, "observedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "records": { "items": { "anyOf": [ { "additionalProperties": false, "properties": { "contentClass": { "anyOf": [ { "const": "operational", "type": "string" }, { "const": "activity", "type": "string" }, { "const": "content", "type": "string" } ] }, "decision": { "additionalProperties": false, "properties": { "binary": { "maxLength": 512, "type": "string" }, "decision": { "anyOf": [ { "const": "denied", "type": "string" }, { "const": "allowed", "type": "string" } ] }, "enforcement": { "anyOf": [ { "const": "blocked", "type": "string" }, { "const": "reported", "type": "string" } ] }, "engine": { "maxLength": 512, "type": "string" }, "host": { "maxLength": 512, "type": "string" }, "policyGeneration": { "maxLength": 512, "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "reason": { "maxLength": 512, "type": "string" }, "rule": { "maxLength": 512, "type": "string" } }, "required": ["decision", "enforcement"], "type": "object" }, "fields": { "additionalProperties": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, "kind": { "anyOf": [ { "const": "wrapper", "type": "string" }, { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" }, { "const": "sandbox", "type": "string" }, { "const": "text", "type": "string" } ] }, "level": { "anyOf": [ { "const": "error", "type": "string" }, { "const": "warn", "type": "string" }, { "const": "info", "type": "string" }, { "const": "debug", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "message": { "maxLength": 8192, "type": "string" }, "stream": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, "subsystem": { "maxLength": 512, "type": "string" }, "time": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "truncated": { "const": true, "type": "boolean" }, "type": { "const": "line", "type": "string" } }, "required": [ "type", "time", "stream", "contentClass", "kind", "level", "message" ], "type": "object" }, { "additionalProperties": false, "properties": { "reason": { "anyOf": [ { "const": "stream_replaced", "type": "string" }, { "const": "window_exceeded", "type": "string" }, { "const": "cursor_expired", "type": "string" }, { "const": "truncated", "type": "string" }, { "const": "buffer_lost", "type": "string" } ] }, "remedy": { "maxLength": 512, "type": "string" }, "stream": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, "time": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "type": { "const": "gap", "type": "string" } }, "required": ["type", "time", "stream", "reason", "remedy"], "type": "object" }, { "additionalProperties": false, "properties": { "count": { "minimum": 1, "type": "integer" }, "reason": { "anyOf": [ { "const": "unrecognised_structured", "type": "string" }, { "const": "oversized", "type": "string" }, { "const": "malformed", "type": "string" } ] }, "stream": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, "time": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "type": { "const": "withheld", "type": "string" } }, "required": ["type", "time", "stream", "count", "reason"], "type": "object" } ] }, "maxItems": 1100, "type": "array" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "stream": { "anyOf": [ { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, { "type": "null" } ] }, "truncated": { "type": "boolean" }, "withheld": { "minimum": 0, "type": "integer" } }, "required": [ "revisionId", "source", "stream", "observedAt", "records", "withheld", "truncated", "cursor" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "title": "AgentRuntimeLogsResponse", "type": "object" }, "def-11": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "transportConfigured": { "type": "boolean" } }, "required": ["transportConfigured"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "title": "AgentRuntimeCredentialResponse", "type": "object" }, "def-12": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "ref": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["id", "namespaceId", "name", "ref"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "title": "SecretResponse", "type": "object" }, "def-13": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "config": { "additionalProperties": { "maxLength": 2048, "minLength": 1, "type": "string" }, "description": "Non-secret source configuration keyed by catalog field name.", "maxProperties": 32, "type": "object" }, "egress": { "additionalProperties": false, "description": "Protected live static, eligible prepared, or explicitly credential-free metadata access. Each profile requires its own grant; missing material never selects credential-free access. Runtime readiness requires current authenticated supervisor evidence.", "properties": { "adoption": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "prepared", "type": "string" }, { "const": "credential_free", "type": "string" } ] }, "retention": { "const": "none", "type": "string" } }, "required": ["adoption", "retention"], "type": "object" }, "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "ownerCapability": { "anyOf": [ { "const": "credential_gateway", "type": "string" }, { "const": "credential_proxy", "type": "string" }, { "const": "token_service", "type": "string" } ], "description": "The Token Service owns saved accounts. Other sources belong to the Driver that admitted them." }, "ref": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "secrets": { "additionalProperties": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "description": "Secret inputs keyed by catalog field name. Each value references an OCC Secret in the same Namespace; OCC never returns its value.", "maxProperties": 16, "type": "object" }, "state": { "anyOf": [ { "const": "registering", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "deleting", "type": "string" } ] }, "status": { "additionalProperties": false, "description": "Source admission or selected Credential Gateway status. For protected sources, ready does not attest an installed enforcing Sandbox; current supervisor evidence is checked separately. Never contains credential values.", "properties": { "reason": { "maxLength": 512, "type": "string" }, "refresh": { "additionalProperties": false, "description": "Token refresh status reported by the selected Credential Refresh Driver for a refresh-type source. It never contains tokens or refresh material.", "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "failureCode": { "maxLength": 128, "type": "string" }, "lastRefreshAt": { "format": "date-time", "type": "string" }, "nextRefreshAt": { "format": "date-time", "type": "string" }, "recoveryAction": { "anyOf": [ { "const": "retry", "type": "string" }, { "const": "reauthorize", "type": "string" }, { "const": "fix_configuration", "type": "string" }, { "const": "investigate", "type": "string" } ] }, "state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" } ] } }, "required": ["state"], "type": "object" }, "state": { "anyOf": [ { "const": "ready", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "absent", "type": "string" } ] } }, "required": ["state"], "type": "object" }, "type": { "description": "Source type from the selected Credential Gateway catalog, for example `openai`.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9-]{0,63}$", "type": "string" } }, "required": [ "id", "namespaceId", "name", "type", "ownerCapability", "config", "secrets", "state", "ref" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "title": "CredentialSourceResponse", "type": "object" }, "def-14": { "additionalProperties": false, "properties": { "authorizationParameters": { "additionalProperties": { "maxLength": 1024, "type": "string" }, "maxProperties": 32, "type": "object" }, "authorizationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "createdAt": { "type": "string" }, "destinations": { "items": { "additionalProperties": false, "properties": { "host": { "type": "string" }, "path": { "type": "string" }, "port": { "type": "integer" } }, "required": ["host", "port", "path"], "type": "object" }, "minItems": 1, "type": "array" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "mcp": { "additionalProperties": false, "properties": { "resource": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "serverUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": ["serverUrl", "resource"], "type": "object" }, "mode": { "anyOf": [ { "const": "manual", "type": "string" }, { "const": "mcp_discovery", "type": "string" } ] }, "oauthClientId": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "observed": { "additionalProperties": false, "properties": { "authorizationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "issuers": { "items": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "type": "array" }, "registrationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "requestedScopes": { "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array" }, "resource": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "resourceScopes": { "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "serverUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "supportedScopes": { "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array" }, "tokenEndpointAuthMethods": { "items": { "type": "string" }, "type": "array" }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": ["serverUrl", "resource", "issuers", "requestedScopes"], "type": "object" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "scopes": { "description": "Scopes approved by the administrator. An empty list leaves scope selection to the account owner and provider.", "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array", "uniqueItems": true }, "templateId": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": [ "templateId", "version", "createdAt", "mode", "issuer", "authorizationUrl", "tokenUrl", "destinations", "scopes", "authorizationParameters" ], "title": "OAuth connection template version", "type": "object" }, "def-15": { "additionalProperties": false, "properties": { "createdAt": { "type": "string" }, "current": { "$ref": "#/components/schemas/def-14" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "id": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["displayName", "id", "current", "createdAt"], "title": "OAuth connection template", "type": "object" }, "def-2": { "items": { "additionalProperties": false, "properties": { "channel": { "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_-]*$", "type": "string" }, "id": { "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u0020\\u007f]+$", "type": "string" } }, "required": ["channel", "id"], "type": "object" }, "maxItems": 64, "title": "PluginApprovers", "type": "array", "uniqueItems": true }, "def-3": { "additionalProperties": false, "minProperties": 1, "properties": { "approval": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "approvers": { "$ref": "#/components/schemas/def-2" }, "enabled": { "type": "boolean" }, "reviewer": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] } }, "title": "PluginToolPolicy", "type": "object" }, "def-4": { "additionalProperties": false, "minProperties": 1, "properties": { "approval": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "enabled": { "type": "boolean" }, "reviewer": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] } }, "title": "PluginToolDefaults", "type": "object" }, "def-5": { "additionalProperties": false, "properties": { "approvers": { "$ref": "#/components/schemas/def-2" }, "driverPolicy": { "additionalProperties": {}, "type": "object" }, "enabled": { "type": "boolean" }, "toolDefaults": { "$ref": "#/components/schemas/def-4" }, "tools": { "additionalProperties": { "$ref": "#/components/schemas/def-3" }, "description": "Tool overrides keyed by exact opaque tool IDs from the selected Plugin Driver catalog.", "propertyNames": { "pattern": "^[^\\u0000-\\u0020\\u007f]{1,1024}$" }, "type": "object" } }, "required": ["enabled"], "title": "PluginDesiredSelection", "type": "object" }, "def-6": { "additionalProperties": { "$ref": "#/components/schemas/def-5" }, "description": "Agent plugin selection map. Keys must be 1-253 characters matching ^[A-Za-z0-9._~:@-]{1,253}$.", "propertyNames": { "pattern": "^[A-Za-z0-9._~:@-]{1,253}$" }, "title": "PluginDesiredState", "type": "object" }, "def-7": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "INVALID_REQUEST", "type": "string" }, { "const": "UNAUTHENTICATED", "type": "string" }, { "const": "FORBIDDEN", "type": "string" }, { "const": "NOT_FOUND", "type": "string" }, { "const": "METHOD_NOT_ALLOWED", "type": "string" }, { "const": "INSTALLATION_EXISTS", "type": "string" }, { "const": "RESOURCE_CONFLICT", "type": "string" }, { "const": "AGENT_DELETING", "type": "string" }, { "const": "NAMESPACE_NOT_READY", "type": "string" }, { "const": "NAMESPACE_NOT_EMPTY", "type": "string" }, { "const": "PAYLOAD_TOO_LARGE", "type": "string" }, { "const": "UNSUPPORTED_MEDIA_TYPE", "type": "string" }, { "const": "UNKNOWN_OUTCOME", "type": "string" }, { "const": "NOT_IMPLEMENTED", "type": "string" }, { "const": "INTERNAL_ERROR", "type": "string" }, { "const": "DEPENDENCY_UNAVAILABLE", "type": "string" }, { "const": "CREDENTIAL_GATEWAY_NOT_CONFIGURED", "description": "The Installation selects no Credential Gateway, so credential sources cannot be registered.", "type": "string" }, { "const": "CREDENTIAL_WITHDRAWAL_IN_PROGRESS", "description": "Only credential withdrawal work still queued or running for an Agent revision that held the source keeps it from being deleted.", "type": "string" }, { "const": "CREDENTIAL_TOKEN_UNSETTLED", "description": "A provider token issued for the source may still be valid after a lost issue or revocation outcome; retry the deletion after the time in the message.", "type": "string" }, { "const": "SANDBOX_POLICY_PROTECTED_EXECUTION", "description": "Protected execution keeps only its Credential Proxy egress policy: Agent network policy additions are refused at save and deploy while the running or next revision is protected, and live application to a protected revision is refused.", "type": "string" }, { "const": "REPOSITORY_GIT_SENDER_UNQUALIFIED", "description": "Deploy is refused because the selected Credential Proxy has no qualified enforcement for the Agent's git-write repository binding; the version could never start.", "type": "string" }, { "const": "REPOSITORY_GIT_PROFILE_UNSUPPORTED", "description": "Deploy is refused because the selected Credential Proxy delivers repository Git only for github-repository bindings, or one git-write or github-installation binding; git-read, git-full or several bindings that are not all github-repository could never start.", "type": "string" }, { "const": "SERVICE_ACCOUNT_DRIVER_NOT_CONFIGURED", "description": "The Installation has no ChatGPT Backend, so service-account credentials cannot be issued, used for Harness authentication, or revoked to delete their account.", "type": "string" }, { "const": "REPOSITORY_OPTIONS_UNAVAILABLE", "description": "Only repository-option discovery is unavailable after Agent create authorization. An Agent without repository bindings may be submitted and is authorized again. Other dependency failures do not carry this meaning.", "type": "string" }, { "const": "MODEL_DISCOVERY_CREDENTIALS_REJECTED", "type": "string" }, { "const": "MODEL_DISCOVERY_RATE_LIMITED", "type": "string" }, { "const": "MODEL_DISCOVERY_UNAVAILABLE", "type": "string" }, { "const": "MODEL_DISCOVERY_INVALID_RESPONSE", "type": "string" }, { "const": "PLUGIN_DISCOVERY_CREDENTIALS_REJECTED", "type": "string" }, { "const": "PLUGIN_DISCOVERY_RATE_LIMITED", "type": "string" }, { "const": "PLUGIN_DISCOVERY_UNAVAILABLE", "type": "string" }, { "const": "PLUGIN_DISCOVERY_INVALID_RESPONSE", "type": "string" }, { "const": "CHANNEL_DIRECTORY_CREDENTIALS_REJECTED", "type": "string" }, { "const": "CHANNEL_DIRECTORY_MISSING_SCOPE", "type": "string" }, { "const": "CHANNEL_DIRECTORY_RATE_LIMITED", "type": "string" }, { "const": "CHANNEL_DIRECTORY_INVALID_RESPONSE", "type": "string" }, { "const": "CHANNEL_DIRECTORY_UNAVAILABLE", "type": "string" }, { "const": "CHANNEL_CREDENTIAL_ROLE_MISMATCH", "type": "string" }, { "const": "CHANNEL_CREDENTIAL_CREDENTIALS_REJECTED", "type": "string" }, { "const": "CHANNEL_CREDENTIAL_UNAVAILABLE", "type": "string" }, { "const": "CHANNEL_CREDENTIAL_BINDING_REQUIRED", "type": "string" }, { "const": "RUNTIME_LOGS_CURSOR_INVALID", "type": "string" }, { "const": "RUNTIME_LOGS_POD_INVALID", "type": "string" }, { "const": "RUNTIME_LOGS_SOURCE_UNAVAILABLE", "type": "string" }, { "const": "NATIVE_ADMIN_RETURN_RATE_LIMITED", "type": "string" }, { "const": "RUNTIME_LOGS_RATE_LIMITED", "type": "string" }, { "const": "RUNTIME_LOGS_CLUSTER_RBAC", "type": "string" }, { "const": "RUNTIME_LOGS_SANDBOX_NOT_FOUND", "type": "string" }, { "const": "RUNTIME_LOGS_UNAVAILABLE", "type": "string" }, { "const": "RUNTIME_LOGS_AUDIT_UNAVAILABLE", "type": "string" }, { "const": "RUNTIME_LOGS_TIMEOUT", "type": "string" }, { "const": "RUNTIME_CREDENTIALS_CLUSTER_RBAC", "type": "string" } ] }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "maxLength": 256, "minLength": 1, "type": "string" }, "reason": { "const": "credential_registration_pending", "description": "On credential source DELETE with 503 DEPENDENCY_UNAVAILABLE, registration may still be completing. Retry after the whole seconds in the Retry-After header; the source remains until deletion completes.", "type": "string" }, "remainingResources": { "description": "Present for NAMESPACE_NOT_EMPTY. Each remaining resource kind reports its total count and up to 20 IDs, only of resources the caller can read. Pending Agent provisioning has no resource IDs. Remove the listed resources and retry to discover any others.", "items": { "additionalProperties": false, "properties": { "count": { "minimum": 0, "type": "integer" }, "ids": { "items": { "maxLength": 200, "minLength": 1, "type": "string" }, "maxItems": 20, "type": "array" }, "kind": { "maxLength": 64, "minLength": 1, "type": "string" } }, "required": ["kind", "count", "ids"], "type": "object" }, "maxItems": 7, "type": "array" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "title": "ErrorResponse", "type": "object" }, "def-8": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "checks": { "items": { "additionalProperties": false, "properties": { "check": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "checkedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, { "type": "null" } ] }, "code": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "component": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "state": { "anyOf": [ { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": ["component", "check", "state", "checkedAt"], "type": "object" }, "maxItems": 32, "type": "array" }, "observedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["revisionId", "observedAt", "checks"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "title": "AgentDeploymentDiagnosticsResponse", "type": "object" }, "def-9": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "harness": { "additionalProperties": false, "description": "The Sandbox Driver reports this provider-owned Harness Sandbox (OpenShell). `lost` means that the Sandbox does not serve this Agent revision. OCC will not restart it. Deploy the Agent again to replace it. `starting` with `HARNESS_RESTARTING` means that the provider is restarting a Harness process that exited.", "properties": { "code": { "anyOf": [ { "const": "SANDBOX_MISSING", "type": "string" }, { "const": "SANDBOX_DELETING", "type": "string" }, { "const": "SANDBOX_STOPPED", "type": "string" }, { "const": "SANDBOX_FAILED", "type": "string" }, { "const": "HARNESS_EXITED", "type": "string" }, { "const": "HARNESS_RESTARTING", "type": "string" }, { "const": "UNAVAILABLE", "type": "string" } ] }, "exitCode": { "description": "Present only with HARNESS_RESTARTING: the Harness process's last exit code.", "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }, "restarts": { "description": "Present only with HARNESS_RESTARTING: the restart number in the current crash loop (1 for a first restart).", "maximum": 4294967295, "minimum": 1, "type": "integer" }, "state": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "starting", "type": "string" }, { "const": "lost", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": ["state"], "type": "object" }, "observedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "pods": { "items": { "additionalProperties": false, "properties": { "cluster": { "anyOf": [ { "const": "control", "type": "string" }, { "const": "execution", "type": "string" } ] }, "containers": { "items": { "additionalProperties": false, "properties": { "lastTermination": { "anyOf": [ { "additionalProperties": false, "properties": { "exitCode": { "anyOf": [{ "type": "integer" }, { "type": "null" }] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ] } }, "required": ["reason", "exitCode", "finishedAt"], "type": "object" }, { "type": "null" } ] }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "ready": { "type": "boolean" }, "reason": { "anyOf": [{ "maxLength": 128, "type": "string" }, { "type": "null" }] }, "restartCount": { "minimum": 0, "type": "integer" }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "const": "waiting", "type": "string" }, { "const": "running", "type": "string" }, { "const": "terminated", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": [ "name", "state", "reason", "ready", "restartCount", "startedAt", "lastTermination" ], "type": "object" }, "maxItems": 16, "type": "array" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "events": { "items": { "additionalProperties": false, "properties": { "container": { "anyOf": [ { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, { "type": "null" } ] }, "count": { "minimum": 1, "type": "integer" }, "lastObservedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "message": { "maxLength": 2048, "type": "string" }, "reason": { "maxLength": 128, "type": "string" }, "type": { "anyOf": [ { "const": "Normal", "type": "string" }, { "const": "Warning", "type": "string" } ] } }, "required": [ "type", "container", "reason", "message", "count", "lastObservedAt" ], "type": "object" }, "maxItems": 100, "type": "array" }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "phase": { "maxLength": 64, "type": "string" }, "ready": { "type": "boolean" }, "role": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" } ] }, "uid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" } }, "required": [ "role", "cluster", "name", "uid", "phase", "ready", "createdAt", "containers", "events" ], "type": "object" }, "maxItems": 16, "type": "array" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "sources": { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "id": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "kind": { "anyOf": [ { "const": "container", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "pods": { "items": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "uid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" } }, "required": ["name", "uid", "container", "restartCount"], "type": "object" }, "maxItems": 256, "type": "array" }, "retention": { "maxLength": 512, "type": "string" }, "unavailableCode": { "const": "NO_POD", "type": "string" } }, "required": ["id", "kind", "pods", "available", "retention"], "type": "object" }, "maxItems": 4, "type": "array" } }, "required": ["revisionId", "observedAt", "pods", "sources"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "title": "AgentRuntimeResponse", "type": "object" } }, "securitySchemes": { "serviceApiKey": { "in": "header", "name": "x-api-key", "type": "apiKey" }, "sessionCookie": { "in": "cookie", "name": "openclaw_occ.session_token", "type": "apiKey" } } }, "info": { "description": "OpenClaw Control Plane HTTP API. Examples use synthetic IDs and credentials. Replace them with values from your Installation. Optional integrations require their configured Drivers. A 202 response accepts work; poll its status before treating it as complete.", "title": "Development OCC API", "version": "0.1.0" }, "openapi": "3.1.0", "paths": { "/api/auth/accounts": { "post": { "description": "Requires administer permission on the Installation. Creates a Better Auth account and an explicit IAM Principal in one transaction. Supplying roleId also creates a binding to that existing IAM Role; omitting roleId creates no grants. Public signup remains disabled.", "operationId": "createAuthAccount", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "email": "admin@example.com", "name": "Documentation administrator", "password": "replace-with-a-unique-password" } } }, "schema": { "additionalProperties": false, "properties": { "email": { "maxLength": 320, "minLength": 3, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" }, "password": { "maxLength": 128, "minLength": 12, "type": "string" }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["email", "password"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "email": "admin@example.com", "id": "user-docs-admin", "name": "Documentation administrator", "principalId": "principal-administrator" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "Created", "properties": { "data": { "additionalProperties": true, "properties": { "email": { "format": "email", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "principalId": { "type": "string" } }, "required": ["id", "email", "name", "principalId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RATE_LIMITED" } }, "schema": { "additionalProperties": false, "description": "Too many account creation requests; wait for Retry-After", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Too many account creation requests; wait for Retry-After" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Create a local auth account as an Installation administrator", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}": { "get": { "description": "Requires a current human Native IAM Installation administrator and trusted Origin. Returns guarded present state, not a receipt for any prior operation.", "operationId": "getAuthAccount", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "disabled": false, "methods": [ { "methodId": "method-password", "providerId": "credential", "subject": "user-docs-admin" } ], "principalId": "principal-administrator", "userId": "user-docs-admin", "version": 1 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "disabled": { "type": "boolean" }, "methods": { "items": { "additionalProperties": false, "properties": { "methodId": { "type": "string" }, "providerId": { "type": "string" }, "subject": { "type": "string" } }, "required": ["methodId", "providerId", "subject"], "type": "object" }, "type": "array" }, "principalId": { "type": "string" }, "userId": { "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": ["userId", "principalId", "version", "disabled", "methods"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Inspect current human account state", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}/disable": { "post": { "description": "Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.", "operationId": "disableAuthAccount", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["expectedVersion"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "userId": "user-docs-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "userId": { "type": "string" } }, "required": ["userId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Disable a human account", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}/enable": { "post": { "description": "Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.", "operationId": "enableAuthAccount", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedVersion": 2 } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["expectedVersion"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "userId": "user-docs-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "userId": { "type": "string" } }, "required": ["userId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Re-enable a disabled human account", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}/enrol": { "post": { "description": "Requires a current human Native IAM Installation administrator and trusted Origin. The account must already have its IAM Principal and exactly one password. Idempotent; enrolment grants no access beyond the account's existing IAM bindings.", "operationId": "enrolAuthAccount", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "created": true, "principalId": "principal-administrator", "userId": "user-docs-admin", "version": 1 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "created": { "type": "boolean" }, "principalId": { "type": "string" }, "userId": { "type": "string" }, "version": { "minimum": 1, "type": "integer" } }, "required": ["userId", "principalId", "version", "created"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Enrol an existing account that activation skipped", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}/methods/{methodId}/detach": { "post": { "description": "Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.", "operationId": "detachAuthMethod", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "method-password" } }, "in": "path", "name": "methodId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["expectedVersion"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "userId": "user-docs-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "userId": { "type": "string" } }, "required": ["userId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Detach an external sign-in identity from an account", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}/providers/google": { "post": { "description": "Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.", "operationId": "attachGoogleIdentity", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedVersion": 1, "subject": "123456789012345678901" } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "subject": { "pattern": "^[\\x21-\\x7E]{1,255}$", "type": "string" } }, "required": ["subject", "expectedVersion"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "userId": "user-docs-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "userId": { "type": "string" } }, "required": ["userId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Attach an exact Google identity to an existing account", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}/providers/oidc": { "post": { "description": "Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.", "operationId": "attachOidcIdentity", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedVersion": 1, "subject": "provider-subject-docs-admin" } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "subject": { "pattern": "^[\\x21-\\x7E]{1,255}$", "type": "string" } }, "required": ["subject", "expectedVersion"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "userId": "user-docs-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "userId": { "type": "string" } }, "required": ["userId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Attach an exact OIDC identity to an existing account", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/accounts/{userId}/revoke": { "post": { "description": "Requires a current human Native IAM Installation administrator who holds every grant of the target account's Principal, trusted Origin and expectedVersion from a guarded account read. Commits state and audit together. An unknown outcome must be inspected without automatic retry; present state does not attribute the earlier request.", "operationId": "revokeAuthAccountSessions", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "user-docs-admin" } }, "in": "path", "name": "userId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["expectedVersion"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "userId": "user-docs-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "userId": { "type": "string" } }, "required": ["userId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Revoke all sessions for a human account", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/providers": { "get": { "description": "List configured browser sign-in methods", "operationId": "getAuthProviders", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "google": false, "oidc": false, "password": true, "sessionBinding": false }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "google": { "type": "boolean" }, "oidc": { "type": "boolean" }, "oidcSignIn": { "additionalProperties": false, "description": "Present only when OIDC sign-in is configured: the Console's button label and the configured authorization endpoint that the start URL must use.", "properties": { "authorizationUrl": { "format": "uri", "type": "string" }, "label": { "maxLength": 40, "minLength": 1, "type": "string" } }, "required": ["label", "authorizationUrl"], "type": "object" }, "password": { "description": "False when password sign-in is recovery-only: ordinary accounts sign in with an external provider, and only the recovery account uses a password.", "type": "boolean" }, "sessionBinding": { "type": "boolean" } }, "required": ["google", "oidc", "password", "sessionBinding"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [], "summary": "List configured browser sign-in methods", "tags": ["Authentication"] } }, "/api/auth/providers/google/callback": { "get": { "description": "Consumes the browser-bound attempt before provider exchange. Redirects to Console after session and audit commit or with a fixed failure classification.", "operationId": "completeGoogleSignIn", "responses": { "302": { "description": "Redirect to Console" } }, "security": [], "summary": "Complete an enrolled Google sign-in", "tags": ["Authentication"] } }, "/api/auth/providers/google/result": { "post": { "description": "Requires the configured browser Origin, the one-use login receipt cookie set by the callback, the matching attemptId and the session cookie that callback issued. Returns that session's sessionKey; never issues or extends a session.", "operationId": "confirmGoogleSignIn", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "attemptId": "example000000000000000000000000000000000000" } } }, "schema": { "additionalProperties": false, "properties": { "attemptId": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": ["attemptId"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "sessionKey": "example-session-binding-not-a-credential" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "sessionKey": { "type": "string" } }, "required": ["sessionKey"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Confirm which session a Google sign-in created", "tags": ["Authentication"] } }, "/api/auth/providers/google/start": { "post": { "description": "Requires the exact configured browser Origin and, when Sec-Fetch-Site is present, same-origin. Creates a one-use browser-bound login attempt and returns its public attemptId for the result exchange; does not create an account or grant access.", "operationId": "startGoogleSignIn", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "attemptId": "example000000000000000000000000000000000000", "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=example&state=example-browser-bound-state" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "attemptId": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": ["url", "attemptId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [], "summary": "Start Google sign-in for an enrolled account", "tags": ["Authentication"] } }, "/api/auth/providers/oidc/callback": { "get": { "description": "Consumes the browser-bound attempt before provider exchange. Redirects to Console after session and audit commit or with a fixed failure classification.", "operationId": "completeOidcSignIn", "responses": { "302": { "description": "Redirect to Console" } }, "security": [], "summary": "Complete an enrolled OIDC sign-in", "tags": ["Authentication"] } }, "/api/auth/providers/oidc/result": { "post": { "description": "Requires the configured browser Origin, the one-use login receipt cookie set by the callback, the matching attemptId and the session cookie that callback issued. Returns that session's sessionKey; never issues or extends a session.", "operationId": "confirmOidcSignIn", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "attemptId": "example000000000000000000000000000000000000" } } }, "schema": { "additionalProperties": false, "properties": { "attemptId": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, "required": ["attemptId"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "sessionKey": "example-session-binding-not-a-credential" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "sessionKey": { "type": "string" } }, "required": ["sessionKey"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Confirm which session an OIDC sign-in created", "tags": ["Authentication"] } }, "/api/auth/providers/oidc/start": { "post": { "description": "Requires the exact configured browser Origin and, when Sec-Fetch-Site is present, same-origin. Creates a one-use browser-bound login attempt and returns its public attemptId for the result exchange; does not create an account or grant access.", "operationId": "startOidcSignIn", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "attemptId": "example000000000000000000000000000000000000", "url": "https://identity.example.com/authorize?client_id=example&state=example-browser-bound-state" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "attemptId": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": ["url", "attemptId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [], "summary": "Start OIDC sign-in for an enrolled account", "tags": ["Authentication"] } }, "/api/auth/recovery": { "get": { "description": "Requires a current human Native IAM Installation administrator and trusted Origin. Returns the present designation, whose password the database protects; not a receipt for any prior operation.", "operationId": "getAuthRecovery", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "methodId": "method-password", "principalId": "principal-administrator", "userId": "user-docs-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "methodId": { "type": "string" }, "principalId": { "type": "string" }, "userId": { "type": "string" } }, "required": ["userId", "principalId", "methodId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Inspect the recovery account designation", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] }, "post": { "description": "Requires a current human Native IAM Installation administrator and trusted Origin who holds every IAM grant of the current holder's Principal (else 403). The target must be an enrolled, enabled account with one password whose Principal administers the Installation. expectedCurrentUserId comes from the recovery read and expectedVersion from the target's account read. Commits state and audit together; an unknown outcome must be inspected without automatic retry.", "operationId": "replaceAuthRecovery", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedCurrentUserId": "user-docs-admin", "expectedVersion": 1, "userId": "user-recovery-admin" } } }, "schema": { "additionalProperties": false, "properties": { "expectedCurrentUserId": { "maxLength": 200, "minLength": 1, "type": "string" }, "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "userId": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["userId", "expectedCurrentUserId", "expectedVersion"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "changed": true, "methodId": "method-recovery-password", "principalId": "principal-recovery-administrator", "userId": "user-recovery-admin" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "changed": { "type": "boolean" }, "methodId": { "type": "string" }, "principalId": { "type": "string" }, "userId": { "type": "string" } }, "required": ["userId", "principalId", "methodId", "changed"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Move the recovery designation to another Installation administrator", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/service-keys": { "post": { "description": "Requires a session or Installation-scoped service key with administer on the Installation. Issues a Better Auth key for an existing non-Agent ServicePrincipal in its exact scope when the caller already holds every IAM grant of that ServicePrincipal at the same or a broader scope; creates no identity or IAM grant. The plaintext key is returned only here.", "operationId": "createServiceKey", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expiresIn": 86400, "name": "Documentation automation", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent" } } }, "schema": { "additionalProperties": false, "properties": { "expiresIn": { "description": "Lifetime in seconds; defaults to 30 days.", "maximum": 31536000, "minimum": 86400, "type": "integer" }, "name": { "maxLength": 32, "minLength": 1, "pattern": "\\S", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["servicePrincipalId", "name"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "expiresAt": "2026-10-02T12:00:00.000Z", "id": "key-docs-automation", "key": "example-key-not-valid-for-authentication", "name": "Documentation automation", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "Created", "properties": { "data": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "namespaceId": { "type": "string" }, "servicePrincipalId": { "type": "string" } }, "required": ["id", "servicePrincipalId", "name", "expiresAt", "key"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }, { "serviceApiKey": [] }], "summary": "Issue a service API key", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/service-keys/{keyId}": { "delete": { "description": "Requires a session or Installation-scoped service key with administer on the Installation, plus every IAM grant of the key's ServicePrincipal, as for issuance. Deletes the stored Better Auth key; subsequent requests cannot authenticate with it.", "operationId": "revokeServiceKey", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "key-docs-automation" } }, "in": "path", "name": "keyId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "key-docs-automation", "revoked": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "revoked": { "const": true, "type": "boolean" } }, "required": ["id", "revoked"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "additionalProperties": false, "description": "Not Found", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "additionalProperties": false, "description": "Conflict", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }, { "serviceApiKey": [] }], "summary": "Revoke a service API key", "tags": ["Authentication"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/api/auth/session": { "get": { "description": "Returns authenticated status, public account identity, and a noncredential sessionKey that stays stable across reads and changes for a new session, or null without a valid session; session tokens and credentials are never returned.", "operationId": "getAuthSession", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": null, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "authenticated": { "const": true, "type": "boolean" }, "sessionKey": { "type": "string" }, "user": { "additionalProperties": false, "properties": { "email": { "format": "email", "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "email", "name"], "type": "object" } }, "required": ["authenticated", "sessionKey", "user"], "type": "object" } ] }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [], "summary": "Inspect authentication without revealing session tokens", "tags": ["Authentication"] } }, "/api/auth/sign-in/email": { "post": { "description": "Authenticates a local account and issues a user session cookie. In both profiles, repeated failed attempts for one email, or from one client address behind a trusted proxy, spend the password budget and may return 429 once it is spent. A successful sign-in also sets an HttpOnly known-device cookie; later attempts for that email from the same browser spend the browser's own budget instead of the email's. The cookie never authenticates. An email with a NUL character or an unpaired UTF-16 surrogate is refused with 400 INVALID_REQUEST and spends budget like a rejected password; the password is not checked for either.", "operationId": "signInEmail", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "email": "admin@example.com", "password": "replace-with-a-unique-password" } } }, "schema": { "additionalProperties": false, "properties": { "email": { "maxLength": 320, "minLength": 3, "type": "string" }, "password": { "maxLength": 128, "minLength": 12, "type": "string" } }, "required": ["email", "password"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "authenticated": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "authenticated": { "const": true, "type": "boolean" }, "sessionKey": { "type": "string" } }, "required": ["authenticated"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "additionalProperties": false, "description": "Bad Request", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "additionalProperties": false, "description": "Payload Too Large", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "additionalProperties": false, "description": "Unsupported Media Type", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unsupported Media Type" }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RATE_LIMITED" } }, "schema": { "additionalProperties": false, "description": "Too Many Requests", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Too Many Requests" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [], "summary": "Sign in with email and password", "tags": ["Authentication"] } }, "/api/auth/sign-out": { "post": { "description": "Revokes the current user session cookie.", "operationId": "signOut", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": {}, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": true, "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "additionalProperties": false, "description": "Unauthorized", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "additionalProperties": false, "description": "Forbidden", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "additionalProperties": false, "description": "Service Unavailable", "properties": { "error": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "type": "array" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["error", "meta"], "type": "object" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Sign out of the current session", "tags": ["Authentication"] } }, "/backends": { "get": { "description": "Requires administer permission on the requested Installation.", "operationId": "listBackends", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "type": { "anyOf": [ { "const": "chatgpt", "type": "string" }, { "const": "github", "type": "string" }, { "const": "openshell", "type": "string" } ] } }, "required": ["id", "type"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List configured Backends (experimental)", "tags": ["Backends"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/connection-templates": { "get": { "description": "Requires administer permission on the requested Installation.", "operationId": "listConnectionTemplates", "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "createdAt": "2026-10-01T12:00:00.000Z", "current": { "authorizationParameters": {}, "authorizationUrl": "https://accounts.example.com/authorize", "createdAt": "2026-10-01T12:00:00.000Z", "destinations": [ { "host": "api.example.com", "path": "/profile", "port": 443 } ], "issuer": "https://accounts.example.com", "mode": "manual", "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000", "scopes": ["profile.read"], "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000", "tokenUrl": "https://accounts.example.com/token", "version": 1 }, "displayName": "Example account", "id": "ctp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/def-15" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List all Installation-wide and Namespace-scoped connection templates", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] }, "post": { "description": "Requires administer permission on the requested Installation.", "operationId": "createConnectionTemplate", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "authorizationUrl": "https://accounts.example.com/authorize", "destinations": [ { "host": "api.example.com", "path": "/profile", "port": 443 } ], "displayName": "Example account", "issuer": "https://accounts.example.com", "mode": "manual", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000", "scopes": ["profile.read"], "tokenUrl": "https://accounts.example.com/token" } } }, "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "authorizationParameters": { "additionalProperties": { "maxLength": 1024, "type": "string" }, "maxProperties": 32, "type": "object" }, "authorizationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "destinations": { "items": { "additionalProperties": false, "properties": { "host": { "maxLength": 253, "minLength": 1, "type": "string" }, "path": { "maxLength": 512, "minLength": 1, "pattern": "^/", "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" } }, "required": ["host"], "type": "object" }, "minItems": 1, "type": "array" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "mode": { "const": "manual", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "oauthClientId": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "scopes": { "description": "Scopes approved by the administrator. An empty list leaves scope selection to the account owner and provider.", "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array", "uniqueItems": true }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": [ "displayName", "scopes", "mode", "issuer", "authorizationUrl", "tokenUrl", "destinations" ], "type": "object" }, { "additionalProperties": false, "properties": { "authorizationParameters": { "additionalProperties": { "maxLength": 1024, "type": "string" }, "maxProperties": 32, "type": "object" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "mode": { "const": "mcp_discovery", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "oauthClientId": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "scopes": { "description": "Scopes approved by the administrator. An empty list leaves scope selection to the account owner and provider.", "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array", "uniqueItems": true }, "serverUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": ["displayName", "scopes", "mode", "serverUrl", "issuer"], "type": "object" } ] } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "current": { "authorizationParameters": {}, "authorizationUrl": "https://accounts.example.com/authorize", "createdAt": "2026-10-01T12:00:00.000Z", "destinations": [ { "host": "api.example.com", "path": "/profile", "port": 443 } ], "issuer": "https://accounts.example.com", "mode": "manual", "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000", "scopes": ["profile.read"], "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000", "tokenUrl": "https://accounts.example.com/token", "version": 1 }, "displayName": "Example account", "id": "ctp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/def-15" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create an Installation-wide or Namespace-scoped connection template", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/connection-templates/discover": { "post": { "description": "Requires administer permission on the requested Installation.", "operationId": "discoverConnectionTemplate", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "serverUrl": "https://tools.example.com/mcp" } } }, "schema": { "additionalProperties": false, "properties": { "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "serverUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": ["serverUrl"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "authorizationUrl": "https://accounts.example.com/authorize", "issuer": "https://accounts.example.com", "issuers": ["https://accounts.example.com"], "requestedScopes": ["profile.read"], "resource": "https://tools.example.com/mcp", "resourceScopes": ["profile.read"], "serverUrl": "https://tools.example.com/mcp", "tokenEndpointAuthMethods": ["client_secret_basic"], "tokenUrl": "https://accounts.example.com/token" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "authorizationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "issuers": { "items": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "type": "array" }, "registrationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "requestedScopes": { "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array" }, "resource": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "resourceScopes": { "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "serverUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "supportedScopes": { "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array" }, "tokenEndpointAuthMethods": { "items": { "type": "string" }, "type": "array" }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": ["serverUrl", "resource", "issuers", "requestedScopes"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read public MCP resource and authorization server metadata", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/connection-templates/{connectionTemplateId}": { "delete": { "description": "Requires administer permission on the requested Installation.", "operationId": "deleteConnectionTemplate", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ctp_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "connectionTemplateId", "required": true, "schema": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete a connection template", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] }, "get": { "description": "Requires administer permission on the requested Installation.", "operationId": "getConnectionTemplate", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ctp_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "connectionTemplateId", "required": true, "schema": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "current": { "authorizationParameters": {}, "authorizationUrl": "https://accounts.example.com/authorize", "createdAt": "2026-10-01T12:00:00.000Z", "destinations": [ { "host": "api.example.com", "path": "/profile", "port": 443 } ], "issuer": "https://accounts.example.com", "mode": "manual", "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000", "scopes": ["profile.read"], "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000", "tokenUrl": "https://accounts.example.com/token", "version": 1 }, "displayName": "Example account", "id": "ctp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/def-15" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get one connection template", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] }, "patch": { "description": "Requires administer permission on the requested Installation.", "operationId": "updateConnectionTemplate", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ctp_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "connectionTemplateId", "required": true, "schema": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "displayName": "Engineering account" } } }, "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "displayName": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["displayName"], "type": "object" }, { "additionalProperties": false, "properties": { "authorizationParameters": { "additionalProperties": { "maxLength": 1024, "type": "string" }, "maxProperties": 32, "type": "object" }, "authorizationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "destinations": { "items": { "additionalProperties": false, "properties": { "host": { "maxLength": 253, "minLength": 1, "type": "string" }, "path": { "maxLength": 512, "minLength": 1, "pattern": "^/", "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" } }, "required": ["host"], "type": "object" }, "minItems": 1, "type": "array" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "mode": { "const": "manual", "type": "string" }, "oauthClientId": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "scopes": { "description": "Scopes approved by the administrator. An empty list leaves scope selection to the account owner and provider.", "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array", "uniqueItems": true }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": [ "scopes", "mode", "issuer", "authorizationUrl", "tokenUrl", "destinations" ], "type": "object" }, { "additionalProperties": false, "properties": { "authorizationParameters": { "additionalProperties": { "maxLength": 1024, "type": "string" }, "maxProperties": 32, "type": "object" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "mode": { "const": "mcp_discovery", "type": "string" }, "oauthClientId": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "scopes": { "description": "Scopes approved by the administrator. An empty list leaves scope selection to the account owner and provider.", "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array", "uniqueItems": true }, "serverUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": ["scopes", "mode", "serverUrl", "issuer"], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "current": { "authorizationParameters": {}, "authorizationUrl": "https://accounts.example.com/authorize", "createdAt": "2026-10-01T12:00:00.000Z", "destinations": [ { "host": "api.example.com", "path": "/profile", "port": 443 } ], "issuer": "https://accounts.example.com", "mode": "manual", "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000", "scopes": ["profile.read"], "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000", "tokenUrl": "https://accounts.example.com/token", "version": 1 }, "displayName": "Engineering account", "id": "ctp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/def-15" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Rename a connection template, or create a version with new approved values", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/installation": { "get": { "description": "Requires read permission on the requested Installation.", "operationId": "getInstallation", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "ins_123e4567-e89b-42d3-a456-426614174000", "name": "Engineering" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "capabilities": { "additionalProperties": false, "properties": { "agentProvisioning": { "additionalProperties": false, "properties": { "executionModes": { "items": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "maxItems": 2, "minItems": 1, "type": "array" } }, "required": ["executionModes"], "type": "object" }, "credentialSources": { "additionalProperties": false, "properties": { "types": { "items": { "additionalProperties": false, "properties": { "config": { "items": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "issuerRotated": { "type": "boolean" }, "name": { "minLength": 1, "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "required"], "type": "object" }, "type": "array" }, "deviceAuthorization": { "additionalProperties": false, "properties": { "harnessId": { "minLength": 1, "type": "string" } }, "required": ["harnessId"], "type": "object" }, "harnessAuth": { "additionalProperties": false, "properties": { "loginMode": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "codex_pat", "type": "string" }, { "const": "chatgptAuthTokens", "type": "string" } ] }, "modelProvider": { "minLength": 1, "type": "string" } }, "required": ["modelProvider", "loginMode"], "type": "object" }, "rotation": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "external", "type": "string" }, { "const": "refresh", "type": "string" } ] }, "secrets": { "items": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "issuerRotated": { "type": "boolean" }, "name": { "minLength": 1, "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "required"], "type": "object" }, "type": "array" }, "type": { "description": "Source type from the selected Credential Gateway catalog, for example `openai`.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9-]{0,63}$", "type": "string" } }, "required": ["type", "config", "secrets", "rotation"], "type": "object" }, "type": "array" } }, "required": ["types"], "type": "object" }, "nativeAdmin": { "const": true, "type": "boolean" }, "nativeWorkers": { "additionalProperties": false, "description": "Present only when dedicated native OpenClaw can be admitted, and says where its native worker support comes from.", "properties": { "support": { "anyOf": [ { "const": "pinned-runtime", "type": "string" }, { "const": "custom-image", "type": "string" } ] } }, "required": ["support"], "type": "object" }, "openclaw": { "additionalProperties": false, "properties": { "executionModes": { "description": "The OpenClaw execution modes this Installation's Sandbox Driver and runtime let an Agent deploy. Agent save refuses Embedded with a selected Sandbox Driver, and Dedicated when the Sandbox Driver's settings refuse it (settingRefusals); it saves Dedicated without a Sandbox Driver that can provision it, which deploy refuses. Empty when no mode can deploy: a selected Sandbox Driver refuses Embedded execution, Dedicated needs one that can provision dedicated OpenClaw with settings that allow it, and a selected Sandbox Driver that is unavailable admits neither.", "items": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "maxItems": 2, "type": "array", "uniqueItems": true }, "sandboxDriverUnavailable": { "const": true, "description": "Present while the selected Sandbox Driver is unavailable. executionModes is then empty until it returns, and Agent save and deploy answer 503 DEPENDENCY_UNAVAILABLE.", "type": "boolean" }, "settingRefusals": { "additionalProperties": false, "description": "Present when the selected Sandbox Driver can provision a mode missing from executionModes but its settings refuse it. Each value is the message Agent save and deploy return for that mode, naming the setting an operator changes. Absent for other reasons a mode is missing.", "properties": { "dedicated": { "minLength": 1, "type": "string" } }, "type": "object" } }, "required": ["executionModes"], "type": "object" }, "pluginCatalogs": { "items": { "additionalProperties": false, "properties": { "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "pluginDiscovery": { "additionalProperties": false, "properties": { "credential": { "anyOf": [ { "const": "required", "type": "string" }, { "const": "none", "type": "string" } ] } }, "required": ["credential"], "type": "object" }, "pluginPolicies": { "additionalProperties": false, "properties": { "approvers": { "additionalProperties": false, "properties": { "agent": { "type": "boolean" }, "plugin": { "type": "boolean" }, "tools": { "type": "boolean" } }, "required": ["agent", "plugin", "tools"], "type": "object" }, "driver": { "$ref": "#/components/schemas/def-1" }, "driverPolicySchema": { "additionalProperties": {}, "type": "object" }, "policyScopeByPlugin": { "additionalProperties": { "const": "enablement_only", "type": "string" }, "type": "object" }, "toolDefaults": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" }, "tools": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" } }, "required": [ "driver", "toolDefaults", "tools", "driverPolicySchema" ], "type": "object" } }, "required": ["harnessId", "pluginPolicies"], "type": "object" }, "type": "array" }, "repositoryAccessRequired": { "const": true, "description": "Present when the selected Credential Proxy confirms it serves only repository Git. Deployment then requires supported repository access. Absence does not guarantee that a deployment will be admitted.", "type": "boolean" } }, "type": "object" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "id": { "pattern": "^ins_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" } }, "required": ["id", "name", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get the singleton Installation", "tags": ["Installation"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "installation", "scope": "requested" } ] } }, "/installation/bootstrap": { "post": { "description": "Requires administer permission on the requested Installation.", "operationId": "bootstrapInstallation", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "name": "Engineering" } } }, "schema": { "additionalProperties": false, "properties": { "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" } }, "required": ["name"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "ins_123e4567-e89b-42d3-a456-426614174000", "name": "Engineering" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "capabilities": { "additionalProperties": false, "properties": { "agentProvisioning": { "additionalProperties": false, "properties": { "executionModes": { "items": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "maxItems": 2, "minItems": 1, "type": "array" } }, "required": ["executionModes"], "type": "object" }, "credentialSources": { "additionalProperties": false, "properties": { "types": { "items": { "additionalProperties": false, "properties": { "config": { "items": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "issuerRotated": { "type": "boolean" }, "name": { "minLength": 1, "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "required"], "type": "object" }, "type": "array" }, "deviceAuthorization": { "additionalProperties": false, "properties": { "harnessId": { "minLength": 1, "type": "string" } }, "required": ["harnessId"], "type": "object" }, "harnessAuth": { "additionalProperties": false, "properties": { "loginMode": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "codex_pat", "type": "string" }, { "const": "chatgptAuthTokens", "type": "string" } ] }, "modelProvider": { "minLength": 1, "type": "string" } }, "required": ["modelProvider", "loginMode"], "type": "object" }, "rotation": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "external", "type": "string" }, { "const": "refresh", "type": "string" } ] }, "secrets": { "items": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "issuerRotated": { "type": "boolean" }, "name": { "minLength": 1, "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "required"], "type": "object" }, "type": "array" }, "type": { "description": "Source type from the selected Credential Gateway catalog, for example `openai`.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9-]{0,63}$", "type": "string" } }, "required": ["type", "config", "secrets", "rotation"], "type": "object" }, "type": "array" } }, "required": ["types"], "type": "object" }, "nativeAdmin": { "const": true, "type": "boolean" }, "nativeWorkers": { "additionalProperties": false, "description": "Present only when dedicated native OpenClaw can be admitted, and says where its native worker support comes from.", "properties": { "support": { "anyOf": [ { "const": "pinned-runtime", "type": "string" }, { "const": "custom-image", "type": "string" } ] } }, "required": ["support"], "type": "object" }, "openclaw": { "additionalProperties": false, "properties": { "executionModes": { "description": "The OpenClaw execution modes this Installation's Sandbox Driver and runtime let an Agent deploy. Agent save refuses Embedded with a selected Sandbox Driver, and Dedicated when the Sandbox Driver's settings refuse it (settingRefusals); it saves Dedicated without a Sandbox Driver that can provision it, which deploy refuses. Empty when no mode can deploy: a selected Sandbox Driver refuses Embedded execution, Dedicated needs one that can provision dedicated OpenClaw with settings that allow it, and a selected Sandbox Driver that is unavailable admits neither.", "items": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "maxItems": 2, "type": "array", "uniqueItems": true }, "sandboxDriverUnavailable": { "const": true, "description": "Present while the selected Sandbox Driver is unavailable. executionModes is then empty until it returns, and Agent save and deploy answer 503 DEPENDENCY_UNAVAILABLE.", "type": "boolean" }, "settingRefusals": { "additionalProperties": false, "description": "Present when the selected Sandbox Driver can provision a mode missing from executionModes but its settings refuse it. Each value is the message Agent save and deploy return for that mode, naming the setting an operator changes. Absent for other reasons a mode is missing.", "properties": { "dedicated": { "minLength": 1, "type": "string" } }, "type": "object" } }, "required": ["executionModes"], "type": "object" }, "pluginCatalogs": { "items": { "additionalProperties": false, "properties": { "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "pluginDiscovery": { "additionalProperties": false, "properties": { "credential": { "anyOf": [ { "const": "required", "type": "string" }, { "const": "none", "type": "string" } ] } }, "required": ["credential"], "type": "object" }, "pluginPolicies": { "additionalProperties": false, "properties": { "approvers": { "additionalProperties": false, "properties": { "agent": { "type": "boolean" }, "plugin": { "type": "boolean" }, "tools": { "type": "boolean" } }, "required": ["agent", "plugin", "tools"], "type": "object" }, "driver": { "$ref": "#/components/schemas/def-1" }, "driverPolicySchema": { "additionalProperties": {}, "type": "object" }, "policyScopeByPlugin": { "additionalProperties": { "const": "enablement_only", "type": "string" }, "type": "object" }, "toolDefaults": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" }, "tools": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" } }, "required": [ "driver", "toolDefaults", "tools", "driverPolicySchema" ], "type": "object" } }, "required": ["harnessId", "pluginPolicies"], "type": "object" }, "type": "array" }, "repositoryAccessRequired": { "const": true, "description": "Present when the selected Credential Proxy confirms it serves only repository Git. Deployment then requires supported repository access. Absence does not guarantee that a deployment will be admitted.", "type": "boolean" } }, "type": "object" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "id": { "pattern": "^ins_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" } }, "required": ["id", "name", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "security": [{ "sessionCookie": [] }], "summary": "Bootstrap the singleton Installation", "tags": ["Installation"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/installation/deployment-inventory": { "get": { "description": "Requires administer permission on the requested Installation.", "operationId": "getInstallationDeploymentInventory", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "installationId": "ins_123e4567-e89b-42d3-a456-426614174000", "namespaces": [ { "agents": [ { "deploymentInProgress": false, "desiredRuntimeState": "stopped", "executionMode": "dedicated", "id": "agt_123e4567-e89b-42d3-a456-426614174000", "status": "active" } ], "id": "ns_123e4567-e89b-42d3-a456-426614174000", "status": "ready" } ] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "installationId": { "pattern": "^ins_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "namespaces": { "items": { "additionalProperties": false, "properties": { "agents": { "items": { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "deploymentInProgress": { "type": "boolean" }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "repositoryWorkerRestart": { "anyOf": [ { "const": "original-worker-required", "type": "string" }, { "const": "reverification-supported", "type": "string" }, { "const": "not-applicable", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "status", "desiredRuntimeState", "executionMode", "deploymentInProgress" ], "type": "object" }, "type": "array" }, "id": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "status": { "anyOf": [ { "const": "provisioning", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": ["id", "status", "agents"], "type": "object" }, "type": "array" } }, "required": ["installationId", "namespaces"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get the complete authorized Agent deployment inventory", "tags": ["Installation"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/installation/driver-configurations": { "get": { "description": "Requires administer permission on the requested Installation.", "operationId": "discoverInstallationConfigurations", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "configurations": [] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "configurations": { "items": { "additionalProperties": false, "properties": { "actions": { "additionalProperties": false, "properties": { "apply": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "read": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "save": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "validate": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" } }, "type": "object" }, "binding": { "anyOf": [ { "const": "installation-startup", "type": "string" }, { "const": "sandbox-policy", "type": "string" } ] }, "capability": { "type": "string" }, "configurationSchema": { "additionalProperties": {}, "type": "object" }, "driverId": { "type": "string" }, "implementation": { "type": "string" }, "key": { "type": "string" }, "scope": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "agent", "type": "string" } ] }, "startupConfiguration": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "type": "object" } }, "required": [ "capability", "driverId", "implementation", "scope", "key", "configurationSchema", "binding", "actions" ], "type": "object" }, "type": "array" } }, "required": ["configurations"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Inspect selected Driver accepted startup values and configuration schemas", "tags": ["Installation"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/namespaces": { "get": { "description": "Only Namespace resources with individual read permission are returned.", "operationId": "listNamespaces", "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "createdAt": "2026-10-01T12:00:00.000Z", "id": "ns_123e4567-e89b-42d3-a456-426614174000", "name": "engineering", "status": "ready" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "existingNamespace": { "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$", "type": "string" }, "id": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "status": { "anyOf": [ { "const": "provisioning", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": ["id", "name", "status", "createdAt"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List authorized Namespaces", "tags": ["Namespaces"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "each_returned" } ] }, "post": { "description": "Requires create permission for Namespace resources in the Installation. Requires administer permission on the Installation when selecting an existing Kubernetes namespace.", "operationId": "createNamespace", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "name": "engineering" } } }, "schema": { "additionalProperties": false, "properties": { "existingNamespace": { "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" } }, "required": ["name"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "ns_123e4567-e89b-42d3-a456-426614174000", "name": "engineering", "status": "provisioning" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "existingNamespace": { "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$", "type": "string" }, "id": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "status": { "anyOf": [ { "const": "provisioning", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": ["id", "name", "status", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create an Installation-owned Namespace", "tags": ["Namespaces"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "namespace", "scope": "installation" }, { "action": "administer", "condition": "existing_namespace", "resourceKind": "installation", "scope": "requested" } ] } }, "/namespaces/{namespaceId}": { "delete": { "description": "Requires delete permission on the requested Namespace.", "operationId": "deleteNamespace", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "ns_123e4567-e89b-42d3-a456-426614174000", "name": "engineering", "status": "deleting" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "existingNamespace": { "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$", "type": "string" }, "id": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "status": { "anyOf": [ { "const": "provisioning", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": ["id", "name", "status", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Begin or retry deletion of an empty Installation-owned Namespace", "tags": ["Namespaces"], "x-openclaw-permissions": [ { "action": "delete", "resourceKind": "namespace", "scope": "requested" } ] }, "get": { "description": "Requires read permission on the requested Namespace.", "operationId": "getNamespace", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "ns_123e4567-e89b-42d3-a456-426614174000", "name": "engineering", "status": "ready" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "existingNamespace": { "maxLength": 63, "minLength": 1, "pattern": "^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?$", "type": "string" }, "id": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "status": { "anyOf": [ { "const": "provisioning", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": ["id", "name", "status", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an exact Installation-owned Namespace", "tags": ["Namespaces"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agent-capabilities": { "get": { "description": "Requires create permission for Agent resources in the requested Namespace.", "operationId": "getNamespaceAgentCapabilities", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "capabilities": { "credentialSources": { "types": [ { "config": [{ "name": "authorized_base_url", "required": false }], "harnessAuth": { "loginMode": "api_key", "modelProvider": "openai" }, "rotation": "external", "secrets": [{ "name": "api_key", "required": true }], "type": "openai" } ] }, "openclaw": { "executionModes": ["dedicated"] } } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "capabilities": { "additionalProperties": false, "description": "The Installation capabilities that apply to Agent creation in this Namespace, as GET /installation reports them. It includes browser-access availability and omits agentProvisioning, which needs Installation administration.", "properties": { "credentialSources": { "additionalProperties": false, "properties": { "types": { "items": { "additionalProperties": false, "properties": { "config": { "items": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "issuerRotated": { "type": "boolean" }, "name": { "minLength": 1, "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "required"], "type": "object" }, "type": "array" }, "deviceAuthorization": { "additionalProperties": false, "properties": { "harnessId": { "minLength": 1, "type": "string" } }, "required": ["harnessId"], "type": "object" }, "harnessAuth": { "additionalProperties": false, "properties": { "loginMode": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "codex_pat", "type": "string" }, { "const": "chatgptAuthTokens", "type": "string" } ] }, "modelProvider": { "minLength": 1, "type": "string" } }, "required": ["modelProvider", "loginMode"], "type": "object" }, "rotation": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "external", "type": "string" }, { "const": "refresh", "type": "string" } ] }, "secrets": { "items": { "additionalProperties": false, "properties": { "description": { "type": "string" }, "issuerRotated": { "type": "boolean" }, "name": { "minLength": 1, "type": "string" }, "required": { "type": "boolean" } }, "required": ["name", "required"], "type": "object" }, "type": "array" }, "type": { "description": "Source type from the selected Credential Gateway catalog, for example `openai`.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9-]{0,63}$", "type": "string" } }, "required": ["type", "config", "secrets", "rotation"], "type": "object" }, "type": "array" } }, "required": ["types"], "type": "object" }, "nativeAdmin": { "const": true, "type": "boolean" }, "nativeWorkers": { "additionalProperties": false, "description": "Present only when dedicated native OpenClaw can be admitted, and says where its native worker support comes from.", "properties": { "support": { "anyOf": [ { "const": "pinned-runtime", "type": "string" }, { "const": "custom-image", "type": "string" } ] } }, "required": ["support"], "type": "object" }, "openclaw": { "additionalProperties": false, "properties": { "executionModes": { "description": "The OpenClaw execution modes this Installation's Sandbox Driver and runtime let an Agent deploy. Agent save refuses Embedded with a selected Sandbox Driver, and Dedicated when the Sandbox Driver's settings refuse it (settingRefusals); it saves Dedicated without a Sandbox Driver that can provision it, which deploy refuses. Empty when no mode can deploy: a selected Sandbox Driver refuses Embedded execution, Dedicated needs one that can provision dedicated OpenClaw with settings that allow it, and a selected Sandbox Driver that is unavailable admits neither.", "items": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "maxItems": 2, "type": "array", "uniqueItems": true }, "sandboxDriverUnavailable": { "const": true, "description": "Present while the selected Sandbox Driver is unavailable. executionModes is then empty until it returns, and Agent save and deploy answer 503 DEPENDENCY_UNAVAILABLE.", "type": "boolean" }, "settingRefusals": { "additionalProperties": false, "description": "Present when the selected Sandbox Driver can provision a mode missing from executionModes but its settings refuse it. Each value is the message Agent save and deploy return for that mode, naming the setting an operator changes. Absent for other reasons a mode is missing.", "properties": { "dedicated": { "minLength": 1, "type": "string" } }, "type": "object" } }, "required": ["executionModes"], "type": "object" }, "pluginCatalogs": { "items": { "additionalProperties": false, "properties": { "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "pluginDiscovery": { "additionalProperties": false, "properties": { "credential": { "anyOf": [ { "const": "required", "type": "string" }, { "const": "none", "type": "string" } ] } }, "required": ["credential"], "type": "object" }, "pluginPolicies": { "additionalProperties": false, "properties": { "approvers": { "additionalProperties": false, "properties": { "agent": { "type": "boolean" }, "plugin": { "type": "boolean" }, "tools": { "type": "boolean" } }, "required": ["agent", "plugin", "tools"], "type": "object" }, "driver": { "$ref": "#/components/schemas/def-1" }, "driverPolicySchema": { "additionalProperties": {}, "type": "object" }, "policyScopeByPlugin": { "additionalProperties": { "const": "enablement_only", "type": "string" }, "type": "object" }, "toolDefaults": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" }, "tools": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" } }, "required": [ "driver", "toolDefaults", "tools", "driverPolicySchema" ], "type": "object" } }, "required": ["harnessId", "pluginPolicies"], "type": "object" }, "type": "array" }, "repositoryAccessRequired": { "const": true, "description": "Present when the selected Credential Proxy confirms it serves only repository Git. Deployment then requires supported repository access. Absence does not guarantee that a deployment will be admitted.", "type": "boolean" } }, "type": "object" } }, "required": ["capabilities"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Report the Installation capabilities that Agent creation in this Namespace needs, for a caller who may create Agents there", "tags": ["Namespaces"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/agents": { "get": { "description": "Requires read permission on the requested Namespace. Only Agent resources with individual read permission are returned.", "operationId": "listAgents", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "backendId": null, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "desiredRuntimeState": "stopped", "executionMode": "dedicated", "gatewayManagedMode": true, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "agt_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent", "status": "active" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "An Agent with readable saved settings, or Agent metadata with configurationReadError (code SAVED_CONFIGURATION_UNREADABLE and the unreadable field). The error variant omits pluginDriver, plugins, pluginApprovers, repositoryBindings, repositoryAccess, harnessAuth, and credentialSources.", "items": { "anyOf": [ { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "pluginDriver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "harnessAuth", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt" ], "type": "object" }, { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "configurationReadError": { "additionalProperties": false, "properties": { "code": { "const": "SAVED_CONFIGURATION_UNREADABLE", "type": "string" }, "field": { "anyOf": [ { "const": "plugins", "type": "string" }, { "const": "pluginApprovers", "type": "string" }, { "const": "repositoryBindings", "type": "string" }, { "const": "repositoryAccess", "type": "string" }, { "const": "harnessAuth", "type": "string" }, { "const": "credentialSources", "type": "string" }, { "const": "secretBindings", "type": "string" }, { "const": "repositoryCredentials", "type": "string" }, { "const": "configuration", "type": "string" } ] } }, "required": ["code", "field"], "type": "object" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt", "configurationReadError" ], "type": "object" } ], "description": "An Agent with readable saved settings, or Agent metadata with configurationReadError (code SAVED_CONFIGURATION_UNREADABLE and the unreadable field). The error variant omits pluginDriver, plugins, pluginApprovers, repositoryBindings, repositoryAccess, harnessAuth, and credentialSources." }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List authorized Agents in one exact Namespace", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "each_returned" } ] }, "post": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires administer permission on the Installation when gatewayManagedMode is set to false. Requires read permission on the requested Configuration. Requires read permission on each currently associated or newly associated ServiceAccount when present. Requires operate permission on each bound Secret when Secret bindings are present or selected. Requires operate permission on each CredentialSource listed in credentialSources or named by a credential-source harnessAuth.", "operationId": "createAgent", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "executionMode": "dedicated", "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "name": "Documentation assistant" } } }, "schema": { "additionalProperties": false, "properties": { "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "expectedConfigurationGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "nativeAdmin": { "description": "Enable Agent browser access with server-derived settings. Requires Configuration update permission, expectedConfigurationGeneration, and an unreferenced Configuration. Chat requires Agent operate; full administration requires Agent administer.", "type": "boolean" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "description": "Requested repository references and optional profiles. Omission means no bindings on create and preserves bindings on update; an empty update clears bindings. Admission requires unique repository references.", "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" }, "workspaceDefaultsId": { "pattern": "^[a-f0-9]{64}$", "type": "string" } }, "required": ["name", "configurationId"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "backendId": null, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "desiredRuntimeState": "stopped", "executionMode": "dedicated", "gatewayManagedMode": true, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "agt_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent", "status": "active" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "pluginDriver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "harnessAuth", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create a Namespace-owned Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "administer", "condition": "gateway_managed_mode_disabled", "resourceKind": "installation", "scope": "installation" }, { "action": "read", "resourceKind": "configuration", "scope": "requested" }, { "action": "read", "condition": "associated_service_account", "resourceKind": "service_account", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" }, { "action": "operate", "condition": "bound_credential_source", "resourceKind": "credential_source", "scope": "request_body" } ] } }, "/namespaces/{namespaceId}/agents/device-authorizations": { "post": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires create permission for Secret resources in the requested Namespace.", "operationId": "startAgentDeviceAuthorization", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "harnessId": "codex" } } }, "schema": { "additionalProperties": false, "properties": { "harnessId": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": ["harnessId"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "expiresAt": "2026-10-01T12:15:00.000Z", "intervalSeconds": 5, "session": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "status": "pending", "userCode": "ABCD-EFGH", "verificationUrl": "https://auth.example.com/device" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "intervalSeconds": { "minimum": 1, "type": "integer" }, "session": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "ready", "type": "string" } ] }, "userCode": { "type": "string" }, "verificationUrl": { "format": "uri", "type": "string" } }, "required": [ "session", "status", "verificationUrl", "userCode", "expiresAt", "intervalSeconds" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Experimental: Start a private device login for Agent configuration", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "create", "resourceKind": "secret", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/agents/device-authorizations/{secretId}": { "delete": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires operate permission on the requested Secret.", "operationId": "cancelAgentDeviceAuthorization", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sec_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "secretId", "required": true, "schema": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Experimental: Discard a local device login without upstream revocation", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "operate", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/device-authorizations/{secretId}/poll": { "post": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires operate permission on the requested Secret.", "operationId": "pollAgentDeviceAuthorization", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sec_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "secretId", "required": true, "schema": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "expiresAt": "2026-10-01T12:15:00.000Z", "intervalSeconds": 5, "session": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "status": "pending", "userCode": "ABCD-EFGH", "verificationUrl": "https://auth.example.com/device" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "intervalSeconds": { "minimum": 1, "type": "integer" }, "session": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "ready", "type": "string" } ] }, "userCode": { "type": "string" }, "verificationUrl": { "format": "uri", "type": "string" } }, "required": [ "session", "status", "verificationUrl", "userCode", "expiresAt", "intervalSeconds" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Experimental: Complete device login without returning credential material", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "operate", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/models": { "post": { "description": "Requires create permission for Agent resources in the requested Namespace.", "operationId": "discoverAgentModels", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "apiKey": "replace-with-your-authorized-model-key", "authMethod": "api_key", "provider": "openai" } } }, "schema": { "additionalProperties": false, "properties": { "apiKey": { "maxLength": 8192, "minLength": 1, "pattern": "\\S", "type": "string", "writeOnly": true }, "authMethod": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "codex_pat", "type": "string" } ] }, "provider": { "anyOf": [ { "const": "openai", "type": "string" }, { "const": "anthropic", "type": "string" } ] } }, "required": ["provider", "authMethod", "apiKey"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/MODEL_DISCOVERY_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List provider models for Agent creation without storing the supplied credential", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/agents/plugins": { "post": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires operate permission on the exact same-Namespace Secret when a Secret reference is supplied.", "operationId": "discoverAgentPlugins", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "harnessId": "codex", "secretRef": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "credentialSource": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "cursor": { "maxLength": 8192, "minLength": 1, "type": "string" }, "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "q": { "maxLength": 1024, "type": "string" } }, "required": ["harnessId", "credentialSource"], "type": "object" }, { "additionalProperties": false, "properties": { "cursor": { "maxLength": 8192, "minLength": 1, "type": "string" }, "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "q": { "maxLength": 1024, "type": "string" } }, "required": ["harnessId"], "type": "object" }, { "additionalProperties": false, "properties": { "accessToken": { "maxLength": 16384, "minLength": 1, "pattern": "\\S", "type": "string", "writeOnly": true }, "cursor": { "maxLength": 8192, "minLength": 1, "type": "string" }, "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "q": { "maxLength": 1024, "type": "string" } }, "required": ["harnessId", "accessToken"], "type": "object" }, { "additionalProperties": false, "properties": { "cursor": { "maxLength": 8192, "minLength": 1, "type": "string" }, "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "q": { "maxLength": 1024, "type": "string" }, "secretRef": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["harnessId", "secretRef"], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "nextCursor": null, "plugins": [ { "description": "Search the documentation service.", "id": "documentation", "name": "Documentation", "tools": null } ] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "nextCursor": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "plugins": { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "privacyPolicyUrl": { "type": "string" }, "remoteId": { "type": "string" }, "selectableWithoutTools": { "type": "boolean" }, "termsOfServiceUrl": { "type": "string" }, "tools": { "anyOf": [ { "type": "null" }, { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "destructive": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "unavailableReason": { "type": "string" }, "writes": { "type": "boolean" } }, "required": ["id", "name", "ownerId"], "type": "object" }, "type": "array" } ] }, "unavailableHelp": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": ["label", "url"], "type": "object" }, "unavailableReason": { "type": "string" }, "websiteUrl": { "type": "string" } }, "required": ["id", "name", "tools"], "type": "object" }, "type": "array" }, "setup": { "additionalProperties": false, "properties": { "links": { "items": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": ["label", "url"], "type": "object" }, "type": "array" }, "message": { "type": "string" } }, "required": ["message", "links"], "type": "object" } }, "required": ["plugins", "nextCursor"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PLUGIN_DISCOVERY_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List or search available plugins for Agent creation using the selected Driver", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "operate", "condition": "selected_secret", "resourceKind": "secret", "scope": "request_body" } ] } }, "/namespaces/{namespaceId}/agents/plugins/details": { "post": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires operate permission on the exact same-Namespace Secret when a Secret reference is supplied.", "operationId": "discoverAgentPluginDetails", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "harnessId": "codex", "pluginId": "documentation", "secretRef": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "credentialSource": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "pluginId": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["harnessId", "pluginId", "credentialSource"], "type": "object" }, { "additionalProperties": false, "properties": { "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "pluginId": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["harnessId", "pluginId"], "type": "object" }, { "additionalProperties": false, "properties": { "accessToken": { "maxLength": 16384, "minLength": 1, "pattern": "\\S", "type": "string", "writeOnly": true }, "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "pluginId": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["harnessId", "pluginId", "accessToken"], "type": "object" }, { "additionalProperties": false, "properties": { "harnessId": { "anyOf": [ { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" } ] }, "pluginId": { "maxLength": 256, "minLength": 1, "type": "string" }, "secretRef": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["harnessId", "pluginId", "secretRef"], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "description": "Search the documentation service.", "id": "documentation", "name": "Documentation", "tools": null }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "privacyPolicyUrl": { "type": "string" }, "remoteId": { "type": "string" }, "selectableWithoutTools": { "type": "boolean" }, "termsOfServiceUrl": { "type": "string" }, "tools": { "anyOf": [ { "type": "null" }, { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "destructive": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "unavailableReason": { "type": "string" }, "writes": { "type": "boolean" } }, "required": ["id", "name", "ownerId"], "type": "object" }, "type": "array" } ] }, "unavailableHelp": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": ["label", "url"], "type": "object" }, "unavailableReason": { "type": "string" }, "websiteUrl": { "type": "string" } }, "required": ["id", "name", "tools"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PLUGIN_DISCOVERY_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read plugin details using the selected Driver", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "operate", "condition": "selected_secret", "resourceKind": "secret", "scope": "request_body" } ] } }, "/namespaces/{namespaceId}/agents/provision": { "post": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires create permission for Configuration resources in the requested Namespace. Requires administer permission on the requested Installation. Requires read permission on each currently associated or newly associated ServiceAccount when present. Requires operate permission on each existing Secret reference supplied in provisioning inputs.", "operationId": "provisionAgent", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "configuration": { "kind": "agent", "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } }, "executionMode": "dedicated", "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "name": "Documentation assistant", "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "schema": { "additionalProperties": false, "properties": { "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configuration": { "additionalProperties": false, "properties": { "kind": { "const": "agent", "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "required": ["kind", "values"], "type": "object" }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ], "description": "Dedicated Harness authentication, required. Omitted, null and `runtime` are refused with 400 INVALID_REQUEST. A ready model `credential_source` is supported when the selected Credential Gateway owns it and the caller has source `operate` permission." }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "nativeAdmin": { "description": "Opt in to native admin UI access on this Agent's exact OCE HTTPS origin before its first deployment. Requires native admin access enabled on the Installation. Defaults to false.", "type": "boolean" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "description": "Requested repository references and optional profiles. Omission means no bindings on create and preserves bindings on update; an empty update clears bindings. Admission requires unique repository references.", "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "workspaceDefaultsId": { "pattern": "^[a-f0-9]{64}$", "type": "string" } }, "required": ["requestId", "name", "configuration"], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "provisioning": { "attemptCount": 0, "phase": "admitted", "requestId": "req_123e4567-e89b-42d3-a456-426614174000", "status": "queued", "updatedAt": "2026-10-01T12:00:00.000Z", "url": "/namespaces/ns_123e4567-e89b-42d3-a456-426614174000/agents/provision/provision-docs-assistant", "workId": "provision-docs-assistant" } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "provisioning": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "attemptCount": { "minimum": 0, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "error": { "additionalProperties": false, "properties": { "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["code", "message"], "type": "object" }, "phase": { "anyOf": [ { "const": "admitted", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "transport", "type": "string" }, { "const": "handoff", "type": "string" } ] }, "progress": { "additionalProperties": false, "description": "Present while a job past handoff is queued or running. The job defers without spending attempts while it waits, so `attemptCount` can stay 0.", "properties": { "lastAttempt": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "at": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" } }, "required": ["at", "code", "message"], "type": "object" } ], "description": "With `agent_revision:read`, this can report the deployment's named wait. Otherwise it reports the job's own `PROVISIONING_DEPLOYMENT_PENDING`, or null if the job has not recorded that wait. The controller writes the message; a refusal can include a code restricted to uppercase letters, digits, and underscores." }, "phase": { "const": "deployment", "description": "Handoff is done; the job waits for its initial deployment.", "type": "string" } }, "required": ["phase", "lastAttempt"], "type": "object" }, "requestId": { "description": "The client request ID stored when this job was admitted. Older controllers omit it. The separate meta.requestId identifies the current HTTP request.", "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "status": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" } ] }, "updatedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "url": { "minLength": 1, "type": "string" }, "workId": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "workId", "status", "phase", "attemptCount", "updatedAt", "url" ], "type": "object" } }, "required": ["provisioning"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create a new Agent and queue first-time provisioning", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "create", "resourceKind": "configuration", "scope": "namespace" }, { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "condition": "associated_service_account", "resourceKind": "service_account", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/provision/{workId}": { "get": { "description": "Requires create permission for Agent and Configuration resources in the requested Namespace and administer permission on the Installation. These are checked from the request path before any lookup, so a caller without them gets 403 whether or not the Namespace or work item exists. Only the principal that started the work can read it. The caller also needs read, operate and deploy permission on the work's Agent and read and update permission on its Configuration once the work has created them, operate permission on each Secret the work binds or uses for Harness authentication, and read permission on its Harness ServiceAccount when present. OCC re-checks these grants against the initiator while the work runs.", "operationId": "getAgentProvisioning", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "provision-docs-assistant" } }, "in": "path", "name": "workId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@/-]{1,200}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "attemptCount": 0, "phase": "admitted", "requestId": "req_123e4567-e89b-42d3-a456-426614174000", "status": "queued", "updatedAt": "2026-10-01T12:00:00.000Z", "url": "/namespaces/ns_123e4567-e89b-42d3-a456-426614174000/agents/provision/provision-docs-assistant", "workId": "provision-docs-assistant" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "attemptCount": { "minimum": 0, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "error": { "additionalProperties": false, "properties": { "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["code", "message"], "type": "object" }, "phase": { "anyOf": [ { "const": "admitted", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "transport", "type": "string" }, { "const": "handoff", "type": "string" } ] }, "progress": { "additionalProperties": false, "description": "Present while a job past handoff is queued or running. The job defers without spending attempts while it waits, so `attemptCount` can stay 0.", "properties": { "lastAttempt": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "at": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" } }, "required": ["at", "code", "message"], "type": "object" } ], "description": "With `agent_revision:read`, this can report the deployment's named wait. Otherwise it reports the job's own `PROVISIONING_DEPLOYMENT_PENDING`, or null if the job has not recorded that wait. The controller writes the message; a refusal can include a code restricted to uppercase letters, digits, and underscores." }, "phase": { "const": "deployment", "description": "Handoff is done; the job waits for its initial deployment.", "type": "string" } }, "required": ["phase", "lastAttempt"], "type": "object" }, "requestId": { "description": "The client request ID stored when this job was admitted. Older controllers omit it. The separate meta.requestId identifies the current HTTP request.", "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "status": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" } ] }, "updatedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "url": { "minLength": 1, "type": "string" }, "workId": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["workId", "status", "phase", "attemptCount", "updatedAt", "url"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get first-time provisioning status for one exact work item", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "create", "resourceKind": "configuration", "scope": "namespace" }, { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "condition": "provisioning_work", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "condition": "provisioning_work", "resourceKind": "agent", "scope": "requested" }, { "action": "deploy", "condition": "provisioning_work", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "condition": "provisioning_work", "resourceKind": "configuration", "scope": "requested" }, { "action": "update", "condition": "provisioning_work", "resourceKind": "configuration", "scope": "requested" }, { "action": "read", "condition": "associated_service_account", "resourceKind": "service_account", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/provision/{workId}/retry": { "post": { "description": "Requires create permission for Agent and Configuration resources in the requested Namespace and administer permission on the Installation. These are checked from the request path before any lookup, so a caller without them gets 403 whether or not the Namespace or work item exists. Only the principal that started the work can retry it. The caller also needs read, operate and deploy permission on the work's Agent and read and update permission on its Configuration once the work has created them, operate permission on each Secret the work binds or uses for Harness authentication, and read permission on its Harness ServiceAccount when present. OCC re-checks these grants against the initiator while the work runs.", "operationId": "retryAgentProvisioning", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "provision-docs-assistant" } }, "in": "path", "name": "workId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@/-]{1,200}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "attemptCount": 0, "phase": "admitted", "requestId": "req_123e4567-e89b-42d3-a456-426614174000", "status": "queued", "updatedAt": "2026-10-01T12:00:00.000Z", "url": "/namespaces/ns_123e4567-e89b-42d3-a456-426614174000/agents/provision/provision-docs-assistant", "workId": "provision-docs-assistant" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "attemptCount": { "minimum": 0, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "error": { "additionalProperties": false, "properties": { "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["code", "message"], "type": "object" }, "phase": { "anyOf": [ { "const": "admitted", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "transport", "type": "string" }, { "const": "handoff", "type": "string" } ] }, "progress": { "additionalProperties": false, "description": "Present while a job past handoff is queued or running. The job defers without spending attempts while it waits, so `attemptCount` can stay 0.", "properties": { "lastAttempt": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "at": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" } }, "required": ["at", "code", "message"], "type": "object" } ], "description": "With `agent_revision:read`, this can report the deployment's named wait. Otherwise it reports the job's own `PROVISIONING_DEPLOYMENT_PENDING`, or null if the job has not recorded that wait. The controller writes the message; a refusal can include a code restricted to uppercase letters, digits, and underscores." }, "phase": { "const": "deployment", "description": "Handoff is done; the job waits for its initial deployment.", "type": "string" } }, "required": ["phase", "lastAttempt"], "type": "object" }, "requestId": { "description": "The client request ID stored when this job was admitted. Older controllers omit it. The separate meta.requestId identifies the current HTTP request.", "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "status": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" } ] }, "updatedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "url": { "minLength": 1, "type": "string" }, "workId": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["workId", "status", "phase", "attemptCount", "updatedAt", "url"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Retry failed first-time provisioning for one exact work item", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "create", "resourceKind": "configuration", "scope": "namespace" }, { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "condition": "provisioning_work", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "condition": "provisioning_work", "resourceKind": "agent", "scope": "requested" }, { "action": "deploy", "condition": "provisioning_work", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "condition": "provisioning_work", "resourceKind": "configuration", "scope": "requested" }, { "action": "update", "condition": "provisioning_work", "resourceKind": "configuration", "scope": "requested" }, { "action": "read", "condition": "associated_service_account", "resourceKind": "service_account", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/repository-options": { "get": { "description": "Requires create permission for Agent resources in the requested Namespace.", "operationId": "listRepositoryOptions", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "allowedProfiles": ["read"], "displayName": "Documentation", "repositoryRef": "documentation" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "allowedProfiles": { "items": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "maxItems": 16, "minItems": 1, "type": "array", "uniqueItems": true }, "description": { "maxLength": 512, "minLength": 1, "type": "string" }, "displayName": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "displayName", "allowedProfiles"], "type": "object" }, "maxItems": 1001, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "notConfigured": { "const": true, "description": "Present when the Installation has no repository settings, so no repository credential Driver is selected. `data` is then empty, and Agent save refuses repository bindings with 409 RESOURCE_CONFLICT.", "type": "boolean" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Check `error.code`: `REPOSITORY_OPTIONS_UNAVAILABLE` means optional repository discovery is unavailable after Namespace lifecycle and Agent create authorization checks, because the selected Compute or Sandbox Driver cannot support repository credentials or the selected repository Driver is unavailable. Without repository settings the answer is 200 with `meta.notConfigured` instead. Creation without repository bindings remains available subject to fresh authorization. `DEPENDENCY_UNAVAILABLE` includes IAM and other required dependency failures and does not permit proceeding. Successful discovery returns a data array, including an empty array when no repositories are approved." } }, "summary": "List approved repository choices for Agent creation in one Namespace", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/agents/validate": { "post": { "description": "Requires create permission for Agent resources in the requested Namespace. Requires administer permission on the Installation when gatewayManagedMode is set to false.", "operationId": "validateAgentCreate", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "configuration": { "kind": "agent", "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } }, "executionMode": "dedicated", "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "name": "Documentation assistant" } } }, "schema": { "additionalProperties": false, "properties": { "configuration": { "additionalProperties": false, "description": "The Agent Configuration the caller will save, not yet saved. With `secretBindings`, a channel credential reference without a binding is refused where Configuration create refuses it (the bundled Kubernetes Compute); the bound Secrets are not read. Without them, that check is skipped.", "properties": { "kind": { "const": "agent", "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "required": ["kind", "values"], "type": "object" }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "additionalProperties": false, "properties": { "method": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "codex_pat", "type": "string" } ] } }, "required": ["method"], "type": "object" }, { "type": "null" } ], "description": "The Harness authentication Agent create will name, so Agent save's check of it against the execution mode and Compute settings runs here too. For a Secret the caller saves next, send only its `method`. The Secret and credential source are not read; omitted or null skips this check." }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "description": "The Agent name create will use. A name that another Agent in the Namespace has is refused with create's `409`.", "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "plugins": { "$ref": "#/components/schemas/def-6" } }, "required": ["configuration"], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Check an unsaved Agent Configuration, plugin selections, initial workspace files and Harness authentication as Configuration and Agent create would, without saving anything", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "agent", "scope": "namespace" }, { "action": "administer", "condition": "gateway_managed_mode_disabled", "resourceKind": "installation", "scope": "installation" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}": { "delete": { "description": "Requires delete permission on the requested Agent.", "operationId": "deleteAgent", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "backendId": null, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "desiredRuntimeState": "stopped", "executionMode": "dedicated", "gatewayManagedMode": true, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "agt_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent", "status": "deleting" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "pluginDriver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "harnessAuth", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Begin or retry deletion of the requested Agent and its Agent revisions", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "delete", "resourceKind": "agent", "scope": "requested" } ] }, "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgent", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "backendId": null, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "desiredRuntimeState": "stopped", "executionMode": "dedicated", "gatewayManagedMode": true, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "agt_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent", "status": "active" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "pluginDriver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "harnessAuth", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt" ], "type": "object" }, { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "configurationReadError": { "additionalProperties": false, "properties": { "code": { "const": "SAVED_CONFIGURATION_UNREADABLE", "type": "string" }, "field": { "anyOf": [ { "const": "plugins", "type": "string" }, { "const": "pluginApprovers", "type": "string" }, { "const": "repositoryBindings", "type": "string" }, { "const": "repositoryAccess", "type": "string" }, { "const": "harnessAuth", "type": "string" }, { "const": "credentialSources", "type": "string" }, { "const": "secretBindings", "type": "string" }, { "const": "repositoryCredentials", "type": "string" }, { "const": "configuration", "type": "string" } ] } }, "required": ["code", "field"], "type": "object" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt", "configurationReadError" ], "type": "object" } ], "description": "An Agent with readable saved settings, or Agent metadata with configurationReadError (code SAVED_CONFIGURATION_UNREADABLE and the unreadable field). The error variant omits pluginDriver, plugins, pluginApprovers, repositoryBindings, repositoryAccess, harnessAuth, and credentialSources." }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an exact Namespace-owned Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] }, "patch": { "description": "Requires update permission on the requested Agent. Requires administer permission on the Installation when the request changes the Agent's saved gatewayManagedMode setting. Requires read permission on the requested Configuration. Requires read permission on each currently associated or newly associated ServiceAccount when present. Requires operate permission on each bound Secret when Secret bindings are present or selected. Requires operate permission on each CredentialSource the Agent lists or names in harnessAuth, before and after the update. Requires read permission on the Agent's SandboxPolicy when it has saved network policy additions and the Agent has repository bindings after the update.", "operationId": "updateAgent", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "executionMode": "dedicated", "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } } } } }, "schema": { "additionalProperties": false, "anyOf": [ { "required": ["configurationId"] }, { "required": ["gatewayManagedMode"] } ], "properties": { "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "pluginApprovers": { "anyOf": [{ "$ref": "#/components/schemas/def-2" }, { "type": "null" }] }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "description": "Requested repository references and optional profiles. Omission means no bindings on create and preserves bindings on update; an empty update clears bindings. Admission requires unique repository references.", "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" }, "repositoryStandingApproval": { "anyOf": [ { "additionalProperties": false, "properties": { "approvalId": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "approved": { "const": true, "type": "boolean" }, "duration": { "const": "until-removed", "type": "string" }, "expectedScopeFingerprint": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "repositoryRef": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": [ "repositoryRef", "approvalId", "approved", "duration", "expectedScopeFingerprint" ], "type": "object" }, { "additionalProperties": false, "properties": { "approvalId": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "approved": { "const": false, "type": "boolean" }, "expectedGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "repositoryRef": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": [ "repositoryRef", "approvalId", "approved", "expectedGeneration" ], "type": "object" } ] } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "backendId": null, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "desiredRuntimeState": "stopped", "executionMode": "dedicated", "gatewayManagedMode": true, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "agt_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent", "status": "active" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "pluginDriver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "harnessAuth", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Replace an exact Namespace-owned Agent's editable draft", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" }, { "action": "administer", "condition": "gateway_managed_mode_changed", "resourceKind": "installation", "scope": "installation" }, { "action": "read", "resourceKind": "configuration", "scope": "requested" }, { "action": "read", "condition": "associated_service_account", "resourceKind": "service_account", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" }, { "action": "operate", "condition": "bound_credential_source", "resourceKind": "credential_source", "scope": "requested" }, { "action": "read", "condition": "saved_sandbox_policy_additions", "resourceKind": "sandbox_policy", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/credential-sources/{credentialSourceId}/withdraw": { "post": { "description": "Requires operate permission on the requested Agent.", "operationId": "withdrawAgentCredentialSource", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cs_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "credentialSourceId", "required": true, "schema": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "credentialSourceId": "cs_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "requestedAt": "2026-10-01T12:00:00.000Z", "requestedBy": "principal-administrator", "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000", "state": "pending", "withdrawalInProgress": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "completedAt": { "format": "date-time", "type": "string" }, "credentialSourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "lastAttemptAt": { "format": "date-time", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "reason": { "description": "Reason code of the worker's most recent attempt, for example `CREDENTIAL_WITHDRAWAL_PENDING` while the gateway has not confirmed revocation.", "pattern": "^[A-Z0-9_]{1,64}$", "type": "string" }, "requestedAt": { "format": "date-time", "type": "string" }, "requestedBy": { "description": "Principal whose `agent:operate` permission the worker re-checks before revoking.", "maxLength": 256, "minLength": 1, "type": "string" }, "revisionId": { "description": "Identifies the Agent revision for the reported withdrawal. This is the selected Agent revision unless another Agent revision that can still run has a `pending` withdrawal for this source. A status read first reports a `pending` withdrawal with no queued or running attempt. `revoked` means every Agent revision that can still run with this source has confirmed withdrawal.", "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "revoked", "type": "string" } ], "description": "`revoked` only after the Credential Gateway confirms that the Agent revision's placeholders no longer resolve." }, "withdrawalInProgress": { "description": "`true` while a withdrawal attempt is queued or running. A `pending` withdrawal with `false` has no queued or running attempt. OCC maintenance can queue a new attempt. To request another attempt, send the withdraw request again.", "type": "boolean" } }, "required": [ "namespaceId", "agentId", "revisionId", "credentialSourceId", "state", "requestedBy", "requestedAt", "withdrawalInProgress" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Revoke one credential source from the selected Agent revision", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/credential-sources/{credentialSourceId}/withdrawal": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgentCredentialWithdrawal", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cs_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "credentialSourceId", "required": true, "schema": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "credentialSourceId": "cs_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "requestedAt": "2026-10-01T12:00:00.000Z", "requestedBy": "principal-administrator", "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000", "state": "pending", "withdrawalInProgress": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "completedAt": { "format": "date-time", "type": "string" }, "credentialSourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "lastAttemptAt": { "format": "date-time", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "reason": { "description": "Reason code of the worker's most recent attempt, for example `CREDENTIAL_WITHDRAWAL_PENDING` while the gateway has not confirmed revocation.", "pattern": "^[A-Z0-9_]{1,64}$", "type": "string" }, "requestedAt": { "format": "date-time", "type": "string" }, "requestedBy": { "description": "Principal whose `agent:operate` permission the worker re-checks before revoking.", "maxLength": 256, "minLength": 1, "type": "string" }, "revisionId": { "description": "Identifies the Agent revision for the reported withdrawal. This is the selected Agent revision unless another Agent revision that can still run has a `pending` withdrawal for this source. A status read first reports a `pending` withdrawal with no queued or running attempt. `revoked` means every Agent revision that can still run with this source has confirmed withdrawal.", "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "revoked", "type": "string" } ], "description": "`revoked` only after the Credential Gateway confirms that the Agent revision's placeholders no longer resolve." }, "withdrawalInProgress": { "description": "`true` while a withdrawal attempt is queued or running. A `pending` withdrawal with `false` has no queued or running attempt. OCC maintenance can queue a new attempt. To request another attempt, send the withdraw request again.", "type": "boolean" } }, "required": [ "namespaceId", "agentId", "revisionId", "credentialSourceId", "state", "requestedBy", "requestedAt", "withdrawalInProgress" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get the withdrawal state of a credential source for an Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/deploy": { "post": { "description": "Requires deploy permission on the requested Agent. Requires read permission on the requested Configuration. Requires read permission on the Agent when the selected Compute Driver must generate missing runtime credentials for its first deployment. Requires operate permission on the Agent when the selected Compute Driver must generate missing runtime credentials for its first deployment. Requires read permission on each currently associated or newly associated ServiceAccount when present. Requires operate permission on each bound Secret when Secret bindings are present or selected. Requires operate permission on each CredentialSource the Agent lists or names in harnessAuth. Requires read permission on the Agent's SandboxPolicy when it has saved network policy additions. Deployment also requires the owning Agent service principal to have operate permission on each bound Secret and on each CredentialSource the Agent lists.", "operationId": "deployAgent", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": { "harnessOverrides": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" } }, "type": "object" } } }, "required": false }, "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "backendId": null, "compute": { "id": "kubernetes", "implementation": "kubernetes" }, "configuration": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } }, "configurationGeneration": 1, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "configurationKind": "agent", "createdAt": "2026-10-01T12:00:00.000Z", "gatewayManagedMode": true, "harness": { "configuration": { "modelProvider": { "baseUrl": "https://api.openai.com/v1", "protocol": "openai-responses", "supportsStandaloneWebSearch": false } }, "id": "codex", "mode": "dedicated", "overrides": {}, "version": "1" }, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "rev_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "revision": 1 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "compute": { "additionalProperties": false, "properties": { "id": { "minLength": 1, "type": "string" }, "implementation": { "minLength": 1, "type": "string" } }, "required": ["id", "implementation"], "type": "object" }, "configuration": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" }, "configurationGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "configurationKind": { "const": "agent", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "gatewayManagedMode": { "description": "Gateway managed mode requested for this Agent version. It does not report Gateway runtime state.", "type": "boolean" }, "harness": { "additionalProperties": false, "properties": { "configuration": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" }, "id": { "minLength": 1, "type": "string" }, "mode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "overrides": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" }, "version": { "minLength": 1, "type": "string" } }, "required": ["id", "version", "mode", "overrides", "configuration"], "type": "object" }, "harnessAuth": { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, "id": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "plugins": { "additionalProperties": false, "properties": { "driver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" } }, "required": ["driver", "plugins"], "type": "object" }, "repositoryCredentials": { "additionalProperties": false, "properties": { "bindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "deadlineWallMs": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "driver": { "additionalProperties": false, "properties": { "id": { "minLength": 1, "type": "string" }, "implementation": { "minLength": 1, "type": "string" } }, "required": ["id", "implementation"], "type": "object" } }, "required": ["driver", "deadlineWallMs", "bindings"], "type": "object" }, "revision": { "minimum": 1, "type": "integer" }, "sandboxDriverId": { "description": "The Sandbox Driver that provisions this version. Absent when the version runs without a Sandbox, so it has no Sandbox log source and records no policy denials.", "minLength": 1, "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "secretDriverId": { "minLength": 1, "type": "string" } }, "required": [ "id", "namespaceId", "agentId", "revision", "backendId", "configurationId", "configurationKind", "configurationGeneration", "configuration", "gatewayManagedMode", "harness", "compute", "harnessAuth", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Save an Agent revision from the Agent's saved settings", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "deploy", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "configuration", "scope": "requested" }, { "action": "read", "condition": "missing_runtime_credentials", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "condition": "missing_runtime_credentials", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "condition": "associated_service_account", "resourceKind": "service_account", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" }, { "action": "operate", "condition": "bound_credential_source", "resourceKind": "credential_source", "scope": "requested" }, { "action": "read", "condition": "saved_sandbox_policy_additions", "resourceKind": "sandbox_policy", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/deploy-first": { "post": { "description": "Fresh admission has the same permissions and conditional access requirements as ordinary deployment. Permissions marked fresh_admission apply only when creating the first revision. Recovery of a matching admission requires only current deploy permission on the exact Agent and read permission on the reviewed Configuration. Requires deploy permission on the requested Agent. Requires read permission on the requested Configuration. Requires read permission on the Agent when the selected Compute Driver must generate missing runtime credentials for its first deployment. Requires operate permission on the Agent when the selected Compute Driver must generate missing runtime credentials for its first deployment. Requires read permission on each currently associated or newly associated ServiceAccount when present. Requires operate permission on each bound Secret when Secret bindings are present or selected. Requires operate permission on each CredentialSource the Agent lists or names in harnessAuth. Requires read permission on the Agent's SandboxPolicy when it has saved network policy additions. Deployment also requires the owning Agent service principal to have operate permission on each bound Secret and on each CredentialSource the Agent lists.", "operationId": "deployAgentFirst", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedConfigurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "expectedGeneration": 1, "key": "review-1" } } }, "schema": { "additionalProperties": false, "properties": { "expectedConfigurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "expectedGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "harnessOverrides": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" }, "key": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._~-]*$", "type": "string" } }, "required": ["key", "expectedConfigurationId", "expectedGeneration"], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "configurationGeneration": 1, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "configurationGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "revisionId", "namespaceId", "agentId", "configurationId", "configurationGeneration", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Admit the first deployment of an exact reviewed Configuration; requires Configuration read", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "deploy", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "configuration", "scope": "requested" }, { "action": "read", "condition": "missing_runtime_credentials", "phase": "fresh_admission", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "condition": "missing_runtime_credentials", "phase": "fresh_admission", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "condition": "associated_service_account", "phase": "fresh_admission", "resourceKind": "service_account", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "phase": "fresh_admission", "resourceKind": "secret", "scope": "requested" }, { "action": "operate", "condition": "bound_credential_source", "phase": "fresh_admission", "resourceKind": "credential_source", "scope": "requested" }, { "action": "read", "condition": "saved_sandbox_policy_additions", "phase": "fresh_admission", "resourceKind": "sandbox_policy", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/deploy-first/{key}/{expectedConfigurationId}/{expectedGeneration}": { "get": { "description": "Requires deploy permission on the exact Agent and read permission on the reviewed Configuration named in the request path. These current permissions are checked for both receipts and misses. Recovery performs no admission or credential preparation.", "operationId": "recoverAgentFirstDeployment", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "{}" } }, "in": "query", "name": "harnessOverrides", "required": false, "schema": { "maxLength": 8192, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "review-1" } }, "in": "path", "name": "key", "required": true, "schema": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._~-]*$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cfg_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "expectedConfigurationId", "required": true, "schema": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "1" } }, "in": "path", "name": "expectedGeneration", "required": true, "schema": { "maxLength": 16, "pattern": "^(?:[1-9][0-9]{0,14}|[1-8][0-9]{15}|900[0-6][0-9]{12}|9007[0-0][0-9]{11}|90071[0-8][0-9]{10}|900719[0-8][0-9]{9}|9007199[0-1][0-9]{8}|90071992[0-4][0-9]{7}|900719925[0-3][0-9]{6}|9007199254[0-6][0-9]{5}|90071992547[0-3][0-9]{4}|9007199254740[0-8][0-9]{2}|90071992547409[0-8][0-9]{1}|900719925474099[0-0][0-9]{0}|9007199254740991)(?![\\s\\S])", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "configurationGeneration": 1, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "configurationGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "revisionId", "namespaceId", "agentId", "configurationId", "configurationGeneration", "createdAt" ], "type": "object" }, { "type": "null" } ] }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "const": "no-store", "type": "string" } } } }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read an exact first-deployment receipt; null does not prove failure; requires Configuration read", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "deploy", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "configuration", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/deployments/{deploymentId}": { "get": { "description": "Requires read permission on the requested Agent revision.", "operationId": "getAgentDeployment", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "rev_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "deploymentId", "required": true, "schema": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "cleanup": null, "deploymentId": "rev_123e4567-e89b-42d3-a456-426614174000", "error": null, "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "progress": null, "status": "succeeded", "warnings": [] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "cleanup": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "nextAttemptAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" } ] } }, "required": ["status", "nextAttemptAt"], "type": "object" } ], "description": "Saved cleanup status for this Agent revision, separate from its deployment result. `null` means no cleanup requirement was recorded. `succeeded` confirms that cleanup is complete." }, "deploymentId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "error": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "data": { "anyOf": [ { "additionalProperties": false, "properties": { "preparation": { "additionalProperties": false, "properties": { "finishedAt": { "anyOf": [ { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "observedAt": { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, "pods": { "items": { "additionalProperties": false, "properties": { "containers": { "items": { "additionalProperties": false, "properties": { "exitCode": { "anyOf": [ { "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "kind": { "anyOf": [ { "const": "init", "type": "string" }, { "const": "main", "type": "string" } ] }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "reason": { "anyOf": [ { "type": "null" }, { "const": "Completed", "type": "string" }, { "const": "Error", "type": "string" }, { "const": "OOMKilled", "type": "string" }, { "const": "ContainerCannotRun", "type": "string" }, { "const": "StartError", "type": "string" }, { "const": "ImagePullBackOff", "type": "string" }, { "const": "ErrImagePull", "type": "string" }, { "const": "CreateContainerConfigError", "type": "string" }, { "const": "CreateContainerError", "type": "string" }, { "const": "RunContainerError", "type": "string" }, { "const": "ContainerCreating", "type": "string" }, { "const": "PodInitializing", "type": "string" } ] }, "startedAt": { "anyOf": [ { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "const": "waiting", "type": "string" }, { "const": "running", "type": "string" }, { "const": "terminated", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": [ "name", "kind", "state", "reason", "exitCode", "startedAt", "finishedAt" ], "type": "object" }, "maxItems": 16, "type": "array" }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "phase": { "anyOf": [ { "const": "Pending", "type": "string" }, { "const": "Running", "type": "string" }, { "const": "Succeeded", "type": "string" }, { "const": "Failed", "type": "string" }, { "const": "Unknown", "type": "string" } ] }, "scheduling": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "scheduled", "type": "string" }, { "const": "unschedulable", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "uid": { "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": [ "name", "uid", "phase", "scheduling", "containers" ], "type": "object" }, "maxItems": 4, "type": "array" }, "reason": { "anyOf": [ { "const": "retry_limit", "type": "string" }, { "const": "deadline", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "startedAt": { "anyOf": [ { "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "workload": { "additionalProperties": false, "properties": { "kind": { "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "namespace": { "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" }, "uid": { "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": ["kind", "name", "uid", "namespace"], "type": "object" } }, "required": [ "workload", "reason", "observedAt", "startedAt", "finishedAt", "pods" ], "type": "object" } }, "required": ["preparation"], "type": "object" }, { "additionalProperties": false, "properties": { "runtimeFailure": { "additionalProperties": false, "properties": { "check": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "checkedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?(?:Z|[+-][0-9]{2}:[0-9]{2})$", "type": "string" }, "code": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "component": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" } }, "required": ["component", "check", "checkedAt", "code"], "type": "object" }, "timeoutMs": { "minimum": 1, "type": "integer" } }, "required": ["timeoutMs"], "type": "object" }, { "additionalProperties": false, "properties": { "runtimeFailure": { "additionalProperties": false, "properties": { "cause": { "additionalProperties": false, "description": "Why the startup model check failed, classified by the runtime.", "properties": { "detail": { "description": "A fixed token for the kind, such as exit-1, signal-SIGKILL, error-ENOBUFS, format, rate_limit, billing, no_model, turn-failed, tool-event, no-reply, json or shape. A Codex token ends -attempt2, such as rate_limit-attempt2, when a retried check failed again. Never native output.", "maxLength": 32, "minLength": 1, "pattern": "^[A-Za-z0-9_-]{1,32}$", "type": "string" }, "kind": { "anyOf": [ { "const": "PROCESS_EXIT", "type": "string" }, { "const": "PROBE_STATUS", "type": "string" }, { "const": "INVALID_OUTPUT", "type": "string" }, { "const": "WRAPPER_ERROR", "type": "string" } ], "description": "PROCESS_EXIT: the check process exited nonzero, was killed or could not run. PROBE_STATUS: the check ran and reported the model unusable. INVALID_OUTPUT: its output was not the expected JSON. WRAPPER_ERROR: the runtime wrapper could not prepare or read the check." } }, "required": ["kind"], "type": "object" }, "check": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "checkedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?(?:Z|[+-][0-9]{2}:[0-9]{2})$", "type": "string" }, "code": { "const": "MODEL_PROBE_FAILED", "type": "string" }, "component": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" } }, "required": ["component", "check", "checkedAt", "code"], "type": "object" } }, "required": ["runtimeFailure"], "type": "object" } ] }, "message": { "minLength": 1, "type": "string" } }, "required": ["code", "message"], "type": "object" } ], "description": "`null` unless deployment failed. A failure contains `code`, a fixed safe message, and optional data with known fields. `CONVERGENCE_DEADLINE_EXCEEDED` can include `data.timeoutMs` and `data.runtimeFailure` with startup failure details. A component, check, or code unknown to the runtime is shown as `UNRECOGNIZED`. `RUNTIME_MODEL_PROBE_FAILED` can include `data.runtimeFailure` with the cause of the failed startup model check. The response never includes native error text." }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "progress": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "lastAttempt": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "at": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "minLength": 1, "type": "string" } }, "required": ["at", "code", "message"], "type": "object" } ], "description": "Latest reconciliation result bound to this exact deployment work item. Null means no bound result is available, not proof that work never ran. Codes and messages are allowlisted; provider text is not exposed." }, "nextAttemptAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, { "type": "null" } ], "description": "Earliest time queued work is eligible to run, not a promised start time. Null while claimed." } }, "required": ["lastAttempt", "nextAttemptAt"], "type": "object" } ], "description": "Pending deployment progress. Null for terminal outcomes. A last attempt describes a recorded result, not current runtime health." }, "repositoryAccess": { "additionalProperties": false, "description": "Present when completed maintenance for this exact revision recorded that repository access requires a new revision. This condition does not change the original deployment result. Absence does not establish current repository access health.", "properties": { "code": { "const": "REPOSITORY_EXECUTION_REDEPLOY_REQUIRED", "type": "string" }, "message": { "type": "string" }, "state": { "const": "redeploy-required", "type": "string" } }, "required": ["state", "code", "message"], "type": "object" }, "status": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" } ] }, "warnings": { "description": "Warnings recorded from this deployment startup. Plugin install and connector-auth warnings mean the deployment succeeded after the runtime disabled the affected admitted plugin for that startup.", "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "PLUGIN_INSTALL_FAILED", "type": "string" }, { "const": "PLUGIN_AUTH_REQUIRED", "type": "string" } ] }, "pluginId": { "description": "The admitted Agent plugin selection key.", "maxLength": 253, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,253}$", "type": "string" } }, "required": ["code", "pluginId"], "type": "object" }, "type": "array" } }, "required": [ "deploymentId", "namespaceId", "agentId", "status", "cleanup", "progress", "error", "warnings" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get the saved deployment status for an Agent revision", "tags": ["Agent deployments"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent_revision", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/deployments/{deploymentId}/diagnostics": { "post": { "description": "Requires operate permission on the requested Agent. Requires read permission on the requested Agent. Requires read permission on the requested Agent revision.", "operationId": "diagnoseAgentDeployment", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "rev_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "deploymentId", "required": true, "schema": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "checks": [ { "check": "running", "checkedAt": "2026-10-01T12:00:00.000Z", "component": "harness", "state": "succeeded" } ], "observedAt": "2026-10-01T12:00:00.000Z", "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "checks": { "items": { "additionalProperties": false, "properties": { "check": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "checkedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, { "type": "null" } ] }, "code": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "component": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@-]{1,64}$", "type": "string" }, "state": { "anyOf": [ { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": ["component", "check", "state", "checkedAt"], "type": "object" }, "maxItems": 32, "type": "array" }, "observedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["revisionId", "observedAt", "checks"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Check the current runtime for an Agent revision", "tags": ["Agent deployments"], "x-openclaw-permissions": [ { "action": "operate", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent_revision", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/deployments/{deploymentId}/runtime": { "get": { "description": "Requires operate permission on the requested Agent. Requires read permission on the requested Agent. Requires read permission on the requested Agent revision.", "operationId": "getAgentDeploymentRuntime", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "rev_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "deploymentId", "required": true, "schema": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "observedAt": "2026-10-01T12:00:00.000Z", "pods": [], "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000", "sources": [ { "available": false, "id": "agent", "kind": "container", "pods": [], "retention": "Pod lifetime", "unavailableCode": "NO_POD" } ] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "harness": { "additionalProperties": false, "description": "The Sandbox Driver reports this provider-owned Harness Sandbox (OpenShell). `lost` means that the Sandbox does not serve this Agent revision. OCC will not restart it. Deploy the Agent again to replace it. `starting` with `HARNESS_RESTARTING` means that the provider is restarting a Harness process that exited.", "properties": { "code": { "anyOf": [ { "const": "SANDBOX_MISSING", "type": "string" }, { "const": "SANDBOX_DELETING", "type": "string" }, { "const": "SANDBOX_STOPPED", "type": "string" }, { "const": "SANDBOX_FAILED", "type": "string" }, { "const": "HARNESS_EXITED", "type": "string" }, { "const": "HARNESS_RESTARTING", "type": "string" }, { "const": "UNAVAILABLE", "type": "string" } ] }, "exitCode": { "description": "Present only with HARNESS_RESTARTING: the Harness process's last exit code.", "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }, "restarts": { "description": "Present only with HARNESS_RESTARTING: the restart number in the current crash loop (1 for a first restart).", "maximum": 4294967295, "minimum": 1, "type": "integer" }, "state": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "starting", "type": "string" }, { "const": "lost", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": ["state"], "type": "object" }, "observedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "pods": { "items": { "additionalProperties": false, "properties": { "cluster": { "anyOf": [ { "const": "control", "type": "string" }, { "const": "execution", "type": "string" } ] }, "containers": { "items": { "additionalProperties": false, "properties": { "lastTermination": { "anyOf": [ { "additionalProperties": false, "properties": { "exitCode": { "anyOf": [{ "type": "integer" }, { "type": "null" }] }, "finishedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ] } }, "required": ["reason", "exitCode", "finishedAt"], "type": "object" }, { "type": "null" } ] }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "ready": { "type": "boolean" }, "reason": { "anyOf": [ { "maxLength": 128, "type": "string" }, { "type": "null" } ] }, "restartCount": { "minimum": 0, "type": "integer" }, "startedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "state": { "anyOf": [ { "const": "waiting", "type": "string" }, { "const": "running", "type": "string" }, { "const": "terminated", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": [ "name", "state", "reason", "ready", "restartCount", "startedAt", "lastTermination" ], "type": "object" }, "maxItems": 16, "type": "array" }, "createdAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "events": { "items": { "additionalProperties": false, "properties": { "container": { "anyOf": [ { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, { "type": "null" } ] }, "count": { "minimum": 1, "type": "integer" }, "lastObservedAt": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "message": { "maxLength": 2048, "type": "string" }, "reason": { "maxLength": 128, "type": "string" }, "type": { "anyOf": [ { "const": "Normal", "type": "string" }, { "const": "Warning", "type": "string" } ] } }, "required": [ "type", "container", "reason", "message", "count", "lastObservedAt" ], "type": "object" }, "maxItems": 100, "type": "array" }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "phase": { "maxLength": 64, "type": "string" }, "ready": { "type": "boolean" }, "role": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" } ] }, "uid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" } }, "required": [ "role", "cluster", "name", "uid", "phase", "ready", "createdAt", "containers", "events" ], "type": "object" }, "maxItems": 16, "type": "array" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "sources": { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "id": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "kind": { "anyOf": [ { "const": "container", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "pods": { "items": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "name": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "uid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" } }, "required": ["name", "uid", "container", "restartCount"], "type": "object" }, "maxItems": 256, "type": "array" }, "retention": { "maxLength": 512, "type": "string" }, "unavailableCode": { "const": "NO_POD", "type": "string" } }, "required": ["id", "kind", "pods", "available", "retention"], "type": "object" }, "maxItems": 4, "type": "array" } }, "required": ["revisionId", "observedAt", "pods", "sources"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RUNTIME_LOGS_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." }, "504": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RUNTIME_LOGS_TIMEOUT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The runtime status or log read timed out." } }, "summary": "Read Pod status, restart counts, Events, and log sources for an Agent revision", "tags": ["Agent deployments"], "x-openclaw-permissions": [ { "action": "operate", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent_revision", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/deployments/{deploymentId}/runtime/logs": { "get": { "description": "Requires read_logs permission on the requested Agent. Without read_logs, administer permission on the requested Agent also admits the read. Requires read permission on the requested Agent.", "operationId": "getAgentDeploymentRuntimeLogs", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agent" } }, "in": "query", "name": "source", "required": true, "schema": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agent-docs-0" } }, "in": "query", "name": "pod", "required": false, "schema": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" } }, { "description": "Actual container in an owned Pod, including init containers. Defaults to the first advertised main container.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agent" } }, "in": "query", "name": "container", "required": false, "schema": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "false" } }, "in": "query", "name": "previous", "required": false, "schema": { "anyOf": [ { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ] } }, { "description": "Lines from the end of the stream, 1 to 1000; default 200.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "100" } }, "in": "query", "name": "tailLines", "required": false, "schema": { "pattern": "^(?:[1-9][0-9]{0,2}|1000)$", "type": "string" } }, { "description": "Only lines newer than this many seconds, 1 to 86400.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "300" } }, "in": "query", "name": "sinceSeconds", "required": false, "schema": { "pattern": "^(?:[1-9][0-9]{0,3}|[1-7][0-9]{4}|8[0-5][0-9]{3}|86[0-3][0-9]{2}|86400)$", "type": "string" } }, { "description": "Return only lines at this level or above; lines of unknown level, gaps and withheld counts are always returned. Default: every level.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "info" } }, "in": "query", "name": "minLevel", "required": false, "schema": { "anyOf": [ { "const": "error", "type": "string" }, { "const": "warn", "type": "string" }, { "const": "info", "type": "string" }, { "const": "debug", "type": "string" } ] } }, { "description": "Opaque cursor returned by the previous page of the same view.", "examples": { "example": { "summary": "Illustrative only: copy an actual cursor from the previous response.", "value": "v1.ZXhhbXBsZQ.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } }, "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 2048, "pattern": "^v[12]\\.[A-Za-z0-9_-]{1,1900}\\.[A-Za-z0-9_-]{43}$", "type": "string" } }, { "description": "`true` returns the last 1000 lines as a text/plain attachment and is audited per download; it cannot be combined with `cursor`.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "false" } }, "in": "query", "name": "download", "required": false, "schema": { "anyOf": [ { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ] } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "rev_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "deploymentId", "required": true, "schema": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "cursor": null, "observedAt": "2026-10-01T12:00:00.000Z", "records": [], "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000", "source": "agent", "stream": null, "truncated": false, "withheld": 0 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "cursor": { "anyOf": [{ "maxLength": 2048, "type": "string" }, { "type": "null" }] }, "observedAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "records": { "items": { "anyOf": [ { "additionalProperties": false, "properties": { "contentClass": { "anyOf": [ { "const": "operational", "type": "string" }, { "const": "activity", "type": "string" }, { "const": "content", "type": "string" } ] }, "decision": { "additionalProperties": false, "properties": { "binary": { "maxLength": 512, "type": "string" }, "decision": { "anyOf": [ { "const": "denied", "type": "string" }, { "const": "allowed", "type": "string" } ] }, "enforcement": { "anyOf": [ { "const": "blocked", "type": "string" }, { "const": "reported", "type": "string" } ] }, "engine": { "maxLength": 512, "type": "string" }, "host": { "maxLength": 512, "type": "string" }, "policyGeneration": { "maxLength": 512, "type": "string" }, "port": { "maximum": 65535, "minimum": 1, "type": "integer" }, "reason": { "maxLength": 512, "type": "string" }, "rule": { "maxLength": 512, "type": "string" } }, "required": ["decision", "enforcement"], "type": "object" }, "fields": { "additionalProperties": { "anyOf": [ { "maxLength": 1024, "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "type": "object" }, "kind": { "anyOf": [ { "const": "wrapper", "type": "string" }, { "const": "openclaw", "type": "string" }, { "const": "codex", "type": "string" }, { "const": "sandbox", "type": "string" }, { "const": "text", "type": "string" } ] }, "level": { "anyOf": [ { "const": "error", "type": "string" }, { "const": "warn", "type": "string" }, { "const": "info", "type": "string" }, { "const": "debug", "type": "string" }, { "const": "unknown", "type": "string" } ] }, "message": { "maxLength": 8192, "type": "string" }, "stream": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, "subsystem": { "maxLength": 512, "type": "string" }, "time": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "truncated": { "const": true, "type": "boolean" }, "type": { "const": "line", "type": "string" } }, "required": [ "type", "time", "stream", "contentClass", "kind", "level", "message" ], "type": "object" }, { "additionalProperties": false, "properties": { "reason": { "anyOf": [ { "const": "stream_replaced", "type": "string" }, { "const": "window_exceeded", "type": "string" }, { "const": "cursor_expired", "type": "string" }, { "const": "truncated", "type": "string" }, { "const": "buffer_lost", "type": "string" } ] }, "remedy": { "maxLength": 512, "type": "string" }, "stream": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, "time": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "type": { "const": "gap", "type": "string" } }, "required": ["type", "time", "stream", "reason", "remedy"], "type": "object" }, { "additionalProperties": false, "properties": { "count": { "minimum": 1, "type": "integer" }, "reason": { "anyOf": [ { "const": "unrecognised_structured", "type": "string" }, { "const": "oversized", "type": "string" }, { "const": "malformed", "type": "string" } ] }, "stream": { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, "time": { "anyOf": [ { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{1,9})?Z$", "type": "string" }, { "type": "null" } ] }, "type": { "const": "withheld", "type": "string" } }, "required": ["type", "time", "stream", "count", "reason"], "type": "object" } ] }, "maxItems": 1100, "type": "array" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] }, "stream": { "anyOf": [ { "additionalProperties": false, "properties": { "container": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "pod": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "podUid": { "maxLength": 64, "minLength": 1, "pattern": "^[A-Za-z0-9-]+$", "type": "string" }, "restartCount": { "minimum": 0, "type": "integer" }, "sandbox": { "maxLength": 253, "minLength": 1, "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$", "type": "string" }, "source": { "anyOf": [ { "const": "gateway", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "sandbox", "type": "string" } ] } }, "required": ["source"], "type": "object" }, { "type": "null" } ] }, "truncated": { "type": "boolean" }, "withheld": { "minimum": 0, "type": "integer" } }, "required": [ "revisionId", "source", "stream", "observedAt", "records", "withheld", "truncated", "cursor" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } }, "text/plain": { "examples": { "example": { "summary": "Log download (download=true)", "value": "2026-10-01T12:00:00.000Z Agent ready\n" } }, "schema": { "description": "The same sanitized records as the JSON page, one per line, for `download=true`.", "type": "string" } } }, "description": "One page of records, or a text/plain attachment when `download=true`" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RUNTIME_LOGS_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." }, "504": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RUNTIME_LOGS_TIMEOUT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The runtime status or log read timed out." } }, "summary": "Read one page of redacted container output for an Agent revision", "tags": ["Agent deployments"], "x-openclaw-permissions": [ { "action": "read_logs", "resourceKind": "agent", "scope": "requested" }, { "action": "administer", "condition": "read_logs_alternative", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/device-authorizations": { "post": { "description": "Requires update permission on the requested Agent. Requires read permission on the requested Agent. Requires create permission for Secret resources in the requested Namespace.", "operationId": "startSavedAgentDeviceAuthorization", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "harnessId": "codex" } } }, "schema": { "additionalProperties": false, "properties": { "harnessId": { "maxLength": 100, "minLength": 1, "type": "string" } }, "required": ["harnessId"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "expiresAt": "2026-10-01T12:15:00.000Z", "intervalSeconds": 5, "session": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "status": "pending", "userCode": "ABCD-EFGH", "verificationUrl": "https://auth.example.com/device" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "intervalSeconds": { "minimum": 1, "type": "integer" }, "session": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "ready", "type": "string" } ] }, "userCode": { "type": "string" }, "verificationUrl": { "format": "uri", "type": "string" } }, "required": [ "session", "status", "verificationUrl", "userCode", "expiresAt", "intervalSeconds" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Experimental: Start a private device login for Agent configuration", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "create", "resourceKind": "secret", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/device-authorizations/{secretId}": { "delete": { "description": "Requires update permission on the requested Agent. Requires read permission on the requested Agent. Requires operate permission on the requested Secret.", "operationId": "cancelSavedAgentDeviceAuthorization", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sec_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "secretId", "required": true, "schema": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Experimental: Discard a local device login without upstream revocation", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/device-authorizations/{secretId}/poll": { "post": { "description": "Requires update permission on the requested Agent. Requires read permission on the requested Agent. Requires operate permission on the requested Secret.", "operationId": "pollSavedAgentDeviceAuthorization", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sec_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "secretId", "required": true, "schema": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "expiresAt": "2026-10-01T12:15:00.000Z", "intervalSeconds": 5, "session": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "status": "pending", "userCode": "ABCD-EFGH", "verificationUrl": "https://auth.example.com/device" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "expiresAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "intervalSeconds": { "minimum": 1, "type": "integer" }, "session": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "ready", "type": "string" } ] }, "userCode": { "type": "string" }, "verificationUrl": { "format": "uri", "type": "string" } }, "required": [ "session", "status", "verificationUrl", "userCode", "expiresAt", "intervalSeconds" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Experimental: Complete device login without returning credential material", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/driver-configurations": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "discoverAgentConfigurations", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "configurations": [] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "configurations": { "items": { "additionalProperties": false, "properties": { "actions": { "additionalProperties": false, "properties": { "apply": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "read": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "save": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "validate": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" } }, "type": "object" }, "binding": { "anyOf": [ { "const": "installation-startup", "type": "string" }, { "const": "sandbox-policy", "type": "string" } ] }, "capability": { "type": "string" }, "configurationSchema": { "additionalProperties": {}, "type": "object" }, "driverId": { "type": "string" }, "implementation": { "type": "string" }, "key": { "type": "string" }, "scope": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "agent", "type": "string" } ] }, "startupConfiguration": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "type": "object" } }, "required": [ "capability", "driverId", "implementation", "scope", "key", "configurationSchema", "binding", "actions" ], "type": "object" }, "type": "array" } }, "required": ["configurations"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Discover authorized Agent Driver configuration contributions", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/harness-status": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgentHarnessStatus", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "status": "unobserved" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "harness": { "additionalProperties": false, "description": "The Sandbox Driver reports this provider-owned Harness Sandbox (OpenShell). `lost` means that the Sandbox does not serve this Agent revision. OCC will not restart it. Deploy the Agent again to replace it. `starting` with `HARNESS_RESTARTING` means that the provider is restarting a Harness process that exited.", "properties": { "code": { "anyOf": [ { "const": "SANDBOX_MISSING", "type": "string" }, { "const": "SANDBOX_DELETING", "type": "string" }, { "const": "SANDBOX_STOPPED", "type": "string" }, { "const": "SANDBOX_FAILED", "type": "string" }, { "const": "HARNESS_EXITED", "type": "string" }, { "const": "HARNESS_RESTARTING", "type": "string" }, { "const": "UNAVAILABLE", "type": "string" } ] }, "exitCode": { "description": "Present only with HARNESS_RESTARTING: the Harness process's last exit code.", "maximum": 2147483647, "minimum": -2147483648, "type": "integer" }, "restarts": { "description": "Present only with HARNESS_RESTARTING: the restart number in the current crash loop (1 for a first restart).", "maximum": 4294967295, "minimum": 1, "type": "integer" }, "state": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "starting", "type": "string" }, { "const": "lost", "type": "string" }, { "const": "unknown", "type": "string" } ] } }, "required": ["state"], "type": "object" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "status": { "anyOf": [ { "const": "observed", "type": "string" }, { "const": "unobserved", "type": "string" } ], "description": "`observed` when OCC read the Sandbox record of the running Agent's active revision. `unobserved` when there is nothing to read: the Agent is stopped, deleting or has no active revision, its Harness is not dedicated, or the selected Sandbox Driver keeps no lifecycle record." } }, "required": ["status"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read the Sandbox Driver's record of a running Agent's dedicated Harness Sandbox", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/native-admin": { "get": { "description": "Requires a human session with operate or administer permission on the exact Agent. Operate grants chat access; administer grants full native administration. Service API keys cannot launch or inspect native admin UI access.", "operationId": "getAgentNativeAdmin", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "status": "stopped" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "activeRevisionId": { "type": "string" }, "host": { "type": "string" }, "mode": { "enum": ["admin", "chat"], "type": "string" }, "origin": { "format": "uri", "type": "string" }, "reason": { "enum": ["not-enabled", "configuration", "compute"], "type": "string" }, "sessionMode": { "enum": ["shared-cookie", "host-only-exchange"], "type": "string" }, "status": { "enum": [ "available", "disabled", "stopped", "unavailable", "unsupported" ], "type": "string" }, "url": { "format": "uri", "type": "string" } }, "required": ["status"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Resolve native admin UI launch availability for one Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "condition": "native_chat", "resourceKind": "agent", "scope": "requested" }, { "action": "administer", "condition": "native_admin_alternative", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/native-admin/confirm": { "post": { "description": "Requires a human session with operate or administer permission on the exact Agent. Operate grants chat access; administer grants full native administration. Service API keys cannot launch or inspect native admin UI access.", "operationId": "confirmAgentNativeAdmin", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sssssssssssssssssssssssssssssssssssssssssss" } }, "in": "header", "name": "x-occ-session-key", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "https://console.example.com" } }, "in": "header", "name": "origin", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "challenge": "ccccccccccccccccccccccccccccccccccccccccccc", "intentId": "123e4567-e89b-42d3-a456-426614174000" } } }, "schema": { "additionalProperties": false, "properties": { "challenge": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "intentId": { "format": "uuid", "type": "string" } }, "required": ["intentId", "challenge"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "exchange": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "intentId": "123e4567-e89b-42d3-a456-426614174000", "redeemUrl": "https://agent-0123456789abcdef0123456789abcdef.agents.example.com/__occ/native-admin/redeem" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "properties": { "data": { "properties": { "exchange": { "type": "string" }, "intentId": { "type": "string" }, "landingUrl": { "type": "string" }, "origin": { "type": "string" }, "redeemUrl": { "type": "string" } }, "required": ["intentId", "exchange", "redeemUrl"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Confirm a native Agent browser challenge", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "condition": "native_chat", "resourceKind": "agent", "scope": "requested" }, { "action": "administer", "condition": "native_admin_alternative", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/native-admin/launch": { "post": { "description": "Requires a human session with operate or administer permission on the exact Agent. Operate grants chat access; administer grants full native administration. Service API keys cannot launch or inspect native admin UI access.", "operationId": "launchAgentNativeAdmin", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sssssssssssssssssssssssssssssssssssssssssss" } }, "in": "header", "name": "x-occ-session-key", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "https://console.example.com" } }, "in": "header", "name": "origin", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "intentId": "123e4567-e89b-42d3-a456-426614174000", "landingUrl": "https://agent-0123456789abcdef0123456789abcdef.agents.example.com/__occ/native-admin/launch?intent=123e4567-e89b-42d3-a456-426614174000", "origin": "https://agent-0123456789abcdef0123456789abcdef.agents.example.com" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "properties": { "data": { "properties": { "exchange": { "type": "string" }, "intentId": { "type": "string" }, "landingUrl": { "type": "string" }, "origin": { "type": "string" }, "redeemUrl": { "type": "string" } }, "required": ["intentId", "origin", "landingUrl"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Conflict" }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Payload Too Large" }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Unsupported Media Type" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Create a browser-bound native Agent launch", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "condition": "native_chat", "resourceKind": "agent", "scope": "requested" }, { "action": "administer", "condition": "native_admin_alternative", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/permissions": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgentCallerPermissions", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "administer": true, "agentSourcesOperate": true, "configurationRead": true, "configurationSecretsOperate": true, "configurationSecretsOperateDeniedBindings": [], "configurationUpdate": true, "delete": true, "deploy": true, "operate": true, "readLogs": true, "sandboxPolicyRead": true, "update": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "administer": { "description": "Whether the selected IAM Driver allows Agent administer now, which native admin UI access needs. Advisory only: other required permissions (native admin UI also needs a signed-in console session), lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "agentSourcesOperate": { "description": "Whether the selected IAM Driver allows, now, the source grants that each Agent update checks: Secret operate on every Secret that the Agent's Configuration binds and on a Secret Harness authentication source, credential source operate on every credential source the Agent lists or uses for Harness authentication, and ServiceAccount read on a ServiceAccount Harness authentication source. `true` when the Agent and its Configuration bind no source. Reported only to a caller with Agent update and Configuration read whose Agent settings are readable; otherwise `false`. Advisory only: other required permissions, lifecycle state, sources that an update adds, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "configurationRead": { "description": "Whether the selected IAM Driver allows read of the Agent's Configuration now, which each Agent update needs. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "configurationSecretsOperate": { "description": "Whether the selected IAM Driver allows Secret operate now on every Secret that the Agent's Configuration binds. Each Configuration save needs it for the Secrets it binds: the Secrets in its `secretBindings`, or every bound Secret when it omits them. `true` when the Configuration binds no Secret. Reported only to a caller with Configuration read and update; otherwise `false`. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "configurationSecretsOperateDeniedBindings": { "description": "The names of the Agent's Configuration Secret bindings whose bound Secret the selected IAM Driver does not allow Secret operate on now, sorted. A Configuration save that submits `secretBindings` needs Secret operate only on the Secrets it submits, so a save that binds each listed name to another Secret does not need it on the Secrets they bind now. A save that omits `secretBindings` keeps every binding. Empty when `configurationSecretsOperate` is `true`, and when it is not reported: reported only to a caller with Configuration read and update. Advisory only: other required permissions, lifecycle state, the Secrets a save binds, or a later authorization decision can still prevent the operation.", "items": { "minLength": 1, "type": "string" }, "maxItems": 64, "type": "array" }, "configurationUpdate": { "description": "Whether the selected IAM Driver allows update of the Agent's Configuration now, which saving its draft Configuration needs. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "delete": { "description": "Whether the selected IAM Driver allows Agent delete now. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "deploy": { "description": "Whether the selected IAM Driver allows Agent deploy now. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "operate": { "description": "Whether the selected IAM Driver allows Agent operate (used for Stop) now. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" }, "readLogs": { "description": "Whether the selected IAM Driver allows reading the Agent's runtime log text now: Agent `read_logs`, or Agent `administer` when no Restriction denies `read_logs`. Advisory only: other required permissions, Compute Driver support, or a later authorization decision can still prevent the read.", "type": "boolean" }, "sandboxPolicyRead": { "description": "Whether the selected IAM Driver allows read now on the Agent's sandbox policy, which reading its network policy and policy suggestions needs. Advisory only: other required permissions, Sandbox Driver support, or a later authorization decision can still prevent the read.", "type": "boolean" }, "update": { "description": "Whether the selected IAM Driver allows Agent update now. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" } }, "required": [ "update", "deploy", "operate", "delete", "administer", "configurationUpdate", "configurationRead", "configurationSecretsOperate", "configurationSecretsOperateDeniedBindings", "agentSourcesOperate", "sandboxPolicyRead", "readLogs" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Report advisory primary IAM permissions on a readable Agent, not authorization for a later operation", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/permissions/secrets": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgentSecretPermissions", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "operateDenied": [], "unreadableOperateDenied": 0 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "operateDenied": { "description": "The IDs of the Namespace's Secrets that the caller may read but the selected IAM Driver does not allow Secret operate on now, sorted. Binding a Secret to this Agent's Configuration or as its Harness authentication source needs Secret operate on it, and so does deploying a draft that binds it. Empty when it is not reported: reported only to a caller with read on the Namespace and on the Agent's Configuration, and update on the Agent or its Configuration or deploy on the Agent. A caller with deploy but neither update gets only the Secrets the draft binds: its Configuration's Secret bindings and a Secret Harness authentication source. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "items": { "minLength": 1, "type": "string" }, "type": "array" }, "unreadableOperateDenied": { "description": "How many of the Secrets the draft binds the caller may neither read nor Secret operate now: its Configuration's Secret bindings and a Secret Harness authentication source. Deploying the draft needs Secret operate on each. A count only: the caller may not read them, so their IDs are never reported. 0 when it is not reported, under the same conditions as `operateDenied`. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "minimum": 0, "type": "integer" } }, "required": ["operateDenied", "unreadableOperateDenied"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Report the readable Secrets that the caller may not bind to a readable Agent, not authorization for a later operation", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/plugins": { "post": { "description": "Requires update permission on the requested Agent. Requires read permission on the requested Agent. Requires operate permission on the Agent's bound Secret when the selected Plugin Driver requires a discovery credential.", "operationId": "discoverSavedAgentPlugins", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": { "credentialSource": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "cursor": { "maxLength": 8192, "minLength": 1, "type": "string" }, "q": { "maxLength": 1024, "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "nextCursor": null, "plugins": [ { "description": "Search the documentation service.", "id": "documentation", "name": "Documentation", "tools": null } ] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "nextCursor": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "plugins": { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "privacyPolicyUrl": { "type": "string" }, "remoteId": { "type": "string" }, "selectableWithoutTools": { "type": "boolean" }, "termsOfServiceUrl": { "type": "string" }, "tools": { "anyOf": [ { "type": "null" }, { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "destructive": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "unavailableReason": { "type": "string" }, "writes": { "type": "boolean" } }, "required": ["id", "name", "ownerId"], "type": "object" }, "type": "array" } ] }, "unavailableHelp": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": ["label", "url"], "type": "object" }, "unavailableReason": { "type": "string" }, "websiteUrl": { "type": "string" } }, "required": ["id", "name", "tools"], "type": "object" }, "type": "array" }, "setup": { "additionalProperties": false, "properties": { "links": { "items": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": ["label", "url"], "type": "object" }, "type": "array" }, "message": { "type": "string" } }, "required": ["message", "links"], "type": "object" } }, "required": ["plugins", "nextCursor"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PLUGIN_DISCOVERY_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List or search plugins for an active Agent; caller needs Agent read/update. Curated discovery needs no Secret; hosted discovery needs the Agent's bound Service Accounts Secret with caller and Agent Secret operate grants", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "condition": "authenticated_plugin_discovery", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/plugins/capabilities": { "get": { "description": "Requires update permission on the requested Agent. Requires read permission on the requested Agent.", "operationId": "getSavedAgentPluginPolicyCapabilities", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "discoveryCredential": "required", "driver": { "id": "codex", "implementation": "codex" }, "driverPolicySchema": {}, "toolDefaults": { "approval": ["all_actions"], "enabled": true, "reviewer": ["human"] }, "tools": { "approval": ["all_actions"], "enabled": true, "reviewer": ["human"] } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "approvers": { "additionalProperties": false, "properties": { "agent": { "type": "boolean" }, "plugin": { "type": "boolean" }, "tools": { "type": "boolean" } }, "required": ["agent", "plugin", "tools"], "type": "object" }, "credentialSlots": { "items": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "pluginId": { "type": "string" }, "releaseSha256": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "sources": { "items": { "additionalProperties": false, "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"], "type": "object" }, "type": "array" }, "toolDiscovery": { "const": true, "type": "boolean" } }, "required": ["pluginId", "releaseSha256", "id", "label", "sources"], "type": "object" }, "type": "array" }, "discoveryCredential": { "anyOf": [ { "const": "required", "type": "string" }, { "const": "none", "type": "string" } ] }, "driver": { "$ref": "#/components/schemas/def-1" }, "driverPolicySchema": { "additionalProperties": {}, "type": "object" }, "policyScopeByPlugin": { "additionalProperties": { "const": "enablement_only", "type": "string" }, "type": "object" }, "toolDefaults": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" }, "tools": { "additionalProperties": false, "properties": { "approval": { "items": { "anyOf": [ { "const": "provider_default", "type": "string" }, { "const": "all_actions", "type": "string" }, { "const": "write_actions", "type": "string" }, { "const": "none", "type": "string" } ] }, "type": "array" }, "enabled": { "type": "boolean" }, "reviewer": { "items": { "anyOf": [ { "const": "human", "type": "string" }, { "const": "auto", "type": "string" } ] }, "type": "array" } }, "required": ["enabled", "approval", "reviewer"], "type": "object" } }, "required": [ "driver", "toolDefaults", "tools", "driverPolicySchema", "discoveryCredential" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read selected Plugin Driver policy capabilities for an active Agent with caller Agent read/update permission", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/plugins/details": { "post": { "description": "Requires update permission on the requested Agent. Requires read permission on the requested Agent. Requires operate permission on the Agent's bound Secret when the selected Plugin Driver requires a discovery credential.", "operationId": "discoverSavedAgentPluginDetails", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "pluginId": "documentation" } } }, "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "credentialSource": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "pluginId": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["pluginId"], "type": "object" }, { "additionalProperties": false, "properties": { "managedConnection": { "additionalProperties": false, "properties": { "slot": { "maxLength": 64, "minLength": 1, "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["slot", "sourceId"], "type": "object" }, "pluginId": { "maxLength": 256, "minLength": 1, "type": "string" } }, "required": ["pluginId", "managedConnection"], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "description": "Search the documentation service.", "id": "documentation", "name": "Documentation", "tools": null }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "id": { "type": "string" }, "logoUrl": { "type": "string" }, "name": { "type": "string" }, "privacyPolicyUrl": { "type": "string" }, "remoteId": { "type": "string" }, "selectableWithoutTools": { "type": "boolean" }, "termsOfServiceUrl": { "type": "string" }, "tools": { "anyOf": [ { "type": "null" }, { "items": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "description": { "type": "string" }, "destructive": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "ownerId": { "type": "string" }, "unavailableReason": { "type": "string" }, "writes": { "type": "boolean" } }, "required": ["id", "name", "ownerId"], "type": "object" }, "type": "array" } ] }, "unavailableHelp": { "additionalProperties": false, "properties": { "label": { "type": "string" }, "url": { "type": "string" } }, "required": ["label", "url"], "type": "object" }, "unavailableReason": { "type": "string" }, "websiteUrl": { "type": "string" } }, "required": ["id", "name", "tools"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PLUGIN_DISCOVERY_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read plugin details for an active Agent with Agent read/update access. Hosted discovery uses the Agent's bound credential. Managed MCP discovery uses an eligible saved connection. The caller and Agent need operate access to the credential", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "operate", "condition": "authenticated_plugin_discovery", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/repository-approval-scopes": { "get": { "description": "Requires administer permission on the requested Agent.", "operationId": "listAgentStandingApprovalScopes", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "properties": { "data": { "items": { "properties": { "binding": { "additionalProperties": {}, "type": "object" }, "repositoryRef": { "type": "string" }, "scope": { "additionalProperties": {}, "type": "object" }, "scopeFingerprint": { "type": "string" } }, "required": ["repositoryRef", "binding", "scope", "scopeFingerprint"], "type": "object" }, "type": "array" }, "meta": { "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Review resolved repository scope before explicitly approving it", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/repository-approvals": { "get": { "description": "Requires administer permission on the requested Agent.", "operationId": "listAgentStandingApprovals", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "properties": { "data": { "items": { "properties": { "approvedBy": { "type": "string" }, "createdAt": { "type": "string" }, "generation": { "minimum": 1, "type": "integer" }, "id": { "type": "string" }, "profile": { "type": "string" }, "repositoryRef": { "type": "string" }, "revokedAt": { "type": "string" }, "scopeFingerprint": { "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "removed", "type": "string" } ] } }, "required": [ "id", "repositoryRef", "profile", "generation", "scopeFingerprint", "status", "approvedBy", "createdAt" ], "type": "object" }, "type": "array" }, "meta": { "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read attributable repository approvals and removed generations for one Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/repository-approvals/{approvalId}/remove": { "post": { "description": "Requires administer permission on the requested Agent.", "operationId": "removeAgentStandingApproval", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "approval-documentation" } }, "in": "path", "name": "approvalId", "required": true, "schema": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedGeneration": 1 } } }, "schema": { "additionalProperties": false, "properties": { "expectedGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": ["expectedGeneration"], "type": "object" } } }, "required": true }, "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Remove repository approval independently of configuration or runtime cleanup", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/repository-options": { "get": { "description": "Requires update permission on the requested Agent.", "operationId": "listAgentRepositoryOptions", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "allowedProfiles": ["read"], "displayName": "Documentation", "repositoryRef": "documentation" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "allowedProfiles": { "items": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "maxItems": 16, "minItems": 1, "type": "array", "uniqueItems": true }, "description": { "maxLength": 512, "minLength": 1, "type": "string" }, "displayName": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "displayName", "allowedProfiles"], "type": "object" }, "maxItems": 1001, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "notConfigured": { "const": true, "description": "Present when the Installation has no repository settings, so no repository credential Driver is selected. `data` is then empty, and Agent save refuses repository bindings with 409 RESOURCE_CONFLICT.", "type": "boolean" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List approved repository choices for updating one Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/revisions": { "get": { "description": "Requires read permission on the requested Agent. Only Agent revision resources with individual read permission are returned.", "operationId": "listAgentRevisions", "parameters": [ { "description": "Agent revisions per page, 1 to 100; default 50.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "20" } }, "in": "query", "name": "limit", "required": false, "schema": { "pattern": "^(?:[1-9][0-9]?|100)$", "type": "string" } }, { "description": "Opaque cursor from `meta.nextCursor` of the previous page.", "examples": { "example": { "summary": "Illustrative only: copy an actual cursor from the previous response.", "value": "v1.1" } }, "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 32, "pattern": "^v1\\.[1-9][0-9]{0,14}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "nextCursor": null, "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "backendId": null, "configurationGeneration": 1, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "deploymentErrorCode": null, "deploymentStatus": "succeeded", "harness": { "configuration": { "modelProvider": { "baseUrl": "https://api.openai.com/v1", "protocol": "openai-responses", "supportsStandaloneWebSearch": false } }, "id": "codex", "mode": "dedicated", "overrides": {}, "version": "1" }, "id": "rev_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "revision": 1 } ], "meta": { "nextCursor": null, "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "description": "Agent revisions that you can read, newest first.", "items": { "description": "Agent revision metadata with the Harness descriptor and any recorded Harness settings, without the native configuration document. Read this Agent revision for its full saved configuration or a `configurationReadError` when those settings are unreadable.", "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "deploymentErrorCode": { "anyOf": [{ "minLength": 1, "type": "string" }, { "type": "null" }], "description": "The `error.code` that reading this revision's deployment would report, or `null` when it reports no error. It tells a failure from a deployment that a newer version or a Stop ended." }, "deploymentStatus": { "anyOf": [ { "const": "queued", "type": "string" }, { "const": "running", "type": "string" }, { "const": "succeeded", "type": "string" }, { "const": "failed", "type": "string" }, { "type": "null" } ], "description": "The status that reading this revision's deployment would report, or `null` when OCC has no deployment record for it." }, "harness": { "additionalProperties": false, "description": "Older revisions omit overrides and configuration when Harness settings were not recorded.", "properties": { "configuration": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" }, "id": { "minLength": 1, "type": "string" }, "mode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "overrides": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" }, "version": { "minLength": 1, "type": "string" } }, "required": ["id", "version", "mode"], "type": "object" }, "id": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revision": { "minimum": 1, "type": "integer" } }, "required": [ "id", "namespaceId", "agentId", "revision", "backendId", "configurationId", "configurationGeneration", "createdAt", "harness", "deploymentStatus", "deploymentErrorCode" ], "type": "object" }, "maxItems": 100, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "nextCursor": { "anyOf": [{ "maxLength": 32, "type": "string" }, { "type": "null" }], "description": "Pass this value as `cursor` to read older Agent revisions. OCC returns a cursor only when it finds an older Agent revision that you can read during this request. A later page can be empty if access changes. `null` means OCC found no older Agent revision that you can read." }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId", "nextCursor"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List Agent revision summaries that you can read for the requested Agent, newest first", "tags": ["Agent revisions"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent_revision", "scope": "each_returned" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/revisions/{revisionId}": { "get": { "description": "Requires read permission on the requested Agent revision.", "operationId": "getAgentRevision", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "rev_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "revisionId", "required": true, "schema": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "backendId": null, "compute": { "id": "kubernetes", "implementation": "kubernetes" }, "configuration": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } }, "configurationGeneration": 1, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "configurationKind": "agent", "createdAt": "2026-10-01T12:00:00.000Z", "gatewayManagedMode": true, "harness": { "configuration": { "modelProvider": { "baseUrl": "https://api.openai.com/v1", "protocol": "openai-responses", "supportsStandaloneWebSearch": false } }, "id": "codex", "mode": "dedicated", "overrides": {}, "version": "1" }, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "rev_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "revision": 1 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "compute": { "additionalProperties": false, "properties": { "id": { "minLength": 1, "type": "string" }, "implementation": { "minLength": 1, "type": "string" } }, "required": ["id", "implementation"], "type": "object" }, "configuration": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" }, "configurationGeneration": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "configurationKind": { "const": "agent", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "gatewayManagedMode": { "description": "Gateway managed mode requested for this Agent version. It does not report Gateway runtime state.", "type": "boolean" }, "harness": { "additionalProperties": false, "properties": { "configuration": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" }, "id": { "minLength": 1, "type": "string" }, "mode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "overrides": { "additionalProperties": {}, "description": "Nonsecret settings owned and validated by the selected Compute Driver.", "type": "object" }, "version": { "minLength": 1, "type": "string" } }, "required": ["id", "version", "mode", "overrides", "configuration"], "type": "object" }, "harnessAuth": { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, "id": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "plugins": { "additionalProperties": false, "properties": { "driver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" } }, "required": ["driver", "plugins"], "type": "object" }, "repositoryCredentials": { "additionalProperties": false, "properties": { "bindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "deadlineWallMs": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "driver": { "additionalProperties": false, "properties": { "id": { "minLength": 1, "type": "string" }, "implementation": { "minLength": 1, "type": "string" } }, "required": ["id", "implementation"], "type": "object" } }, "required": ["driver", "deadlineWallMs", "bindings"], "type": "object" }, "revision": { "minimum": 1, "type": "integer" }, "sandboxDriverId": { "description": "The Sandbox Driver that provisions this version. Absent when the version runs without a Sandbox, so it has no Sandbox log source and records no policy denials.", "minLength": 1, "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "secretDriverId": { "minLength": 1, "type": "string" } }, "required": [ "id", "namespaceId", "agentId", "revision", "backendId", "configurationId", "configurationKind", "configurationGeneration", "configuration", "gatewayManagedMode", "harness", "compute", "harnessAuth", "createdAt" ], "type": "object" }, { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationReadError": { "additionalProperties": false, "properties": { "code": { "const": "SAVED_CONFIGURATION_UNREADABLE", "type": "string" }, "field": { "anyOf": [ { "const": "plugins", "type": "string" }, { "const": "pluginApprovers", "type": "string" }, { "const": "repositoryBindings", "type": "string" }, { "const": "repositoryAccess", "type": "string" }, { "const": "harnessAuth", "type": "string" }, { "const": "credentialSources", "type": "string" }, { "const": "secretBindings", "type": "string" }, { "const": "repositoryCredentials", "type": "string" }, { "const": "configuration", "type": "string" } ] } }, "required": ["code", "field"], "type": "object" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "id": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revision": { "minimum": 1, "type": "integer" } }, "required": [ "id", "namespaceId", "agentId", "revision", "backendId", "createdAt", "configurationReadError" ], "type": "object" } ], "description": "Returns an Agent revision with saved settings that cannot change. If OCC cannot read them, the response omits saved configuration fields and includes `configurationReadError` with code `SAVED_CONFIGURATION_UNREADABLE` and the unreadable field." }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an Agent revision that you can read", "tags": ["Agent revisions"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent_revision", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/revisions/{revisionId}/sandbox-policy/{facet}/recommendations": { "get": { "description": "Requires read permission on the requested Agent. Requires read permission on the requested SandboxPolicy.", "operationId": "getAgentSandboxRecommendations", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "networking" } }, "in": "path", "name": "facet", "required": true, "schema": { "anyOf": [ { "const": "networking", "type": "string" }, { "const": "filesystem", "type": "string" }, { "const": "process", "type": "string" } ] } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "rev_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "revisionId", "required": true, "schema": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "recommendations": [], "truncated": false }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "providerVersion": { "maxLength": 128, "type": "string" }, "recommendations": { "items": { "additionalProperties": false, "properties": { "grant": { "additionalProperties": false, "properties": { "binary": { "description": "Absolute path of the executable receiving access.", "maxLength": 512, "minLength": 2, "pattern": "^/[^\\s\\x00-\\x1f]+$", "title": "Executable path", "type": "string" }, "host": { "description": "DNS hostname or permitted single-label wildcard. Grants allow access; omitted destinations stay denied.", "maxLength": 253, "minLength": 1, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "title": "Destination hostname", "type": "string" }, "id": { "pattern": "^[a-z][a-z0-9-]{0,47}$", "title": "Rule ID", "type": "string" }, "ports": { "items": { "additionalProperties": false, "properties": { "from": { "maximum": 65535, "minimum": 1, "title": "Start port", "type": "integer" }, "to": { "maximum": 65535, "minimum": 1, "title": "End port", "type": "integer" } }, "required": ["from", "to"], "type": "object" }, "maxItems": 16, "minItems": 1, "title": "Port ranges", "type": "array" } }, "required": ["id", "binary", "host", "ports"], "type": "object" }, "id": { "type": "string" }, "observations": { "minimum": 0, "type": "integer" }, "status": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "approved", "type": "string" }, { "const": "rejected", "type": "string" } ] } }, "required": ["id", "status", "grant"], "type": "object" }, "maxItems": 32, "type": "array" }, "truncated": { "type": "boolean" } }, "required": ["recommendations", "truncated"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RUNTIME_LOGS_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read policy suggestions for the requested Agent revision", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "sandbox_policy", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/runtime-credentials": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgentRuntimeCredentials", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "transportConfigured": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "transportConfigured": { "type": "boolean" } }, "required": ["transportConfigured"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get metadata for one Agent's provisioned runtime credentials", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] }, "post": { "description": "Requires operate permission on the requested Agent. Requires read permission on the requested Agent.", "operationId": "provisionAgentRuntimeCredentials", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "transportConfigured": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "transportConfigured": { "type": "boolean" } }, "required": ["transportConfigured"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Provision initial runtime credentials for one undeployed Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/runtime-images": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgentRuntimeImages", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "images": [], "status": "undeployed" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "images": { "items": { "additionalProperties": false, "properties": { "commit": { "anyOf": [ { "pattern": "^[a-f0-9]{40}$", "type": "string" }, { "type": "null" } ] }, "container": { "type": "string" }, "image": { "type": "string" }, "imageId": { "anyOf": [{ "type": "string" }, { "type": "null" }] }, "openclawCommit": { "anyOf": [ { "pattern": "^[a-f0-9]{40}$", "type": "string" }, { "type": "null" } ] }, "workload": { "type": "string" } }, "required": [ "workload", "container", "image", "imageId", "commit", "openclawCommit" ], "type": "object" }, "type": "array" }, "status": { "anyOf": [ { "const": "observed", "type": "string" }, { "const": "undeployed", "type": "string" }, { "const": "unsupported", "type": "string" } ] } }, "required": ["status", "images"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read observed images and source commits for an Agent's active runtime", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/sandbox-policy/{facet}": { "get": { "description": "Requires read permission on the requested Agent. Requires read permission on the requested SandboxPolicy.", "operationId": "getAgentSandboxPolicy", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "networking" } }, "in": "path", "name": "facet", "required": true, "schema": { "anyOf": [ { "const": "networking", "type": "string" }, { "const": "filesystem", "type": "string" }, { "const": "process", "type": "string" } ] } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "capability": null, "ceiling": [], "defaults": null, "editingEnabled": true, "policy": { "additions": [], "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "id": "sbp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "version": 1 }, "protectedExecution": false }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "capability": { "anyOf": [ { "type": "null" }, { "additionalProperties": false, "properties": { "live": { "type": "boolean" }, "portRanges": { "type": "boolean" }, "wildcards": { "type": "boolean" } }, "required": ["wildcards", "portRanges", "live"], "type": "object" } ] }, "ceiling": { "items": { "additionalProperties": false, "properties": { "binary": { "description": "Absolute path of the executable receiving access.", "maxLength": 512, "minLength": 2, "pattern": "^/[^\\s\\x00-\\x1f]+$", "title": "Executable path", "type": "string" }, "host": { "description": "DNS hostname or permitted single-label wildcard. Grants allow access; omitted destinations stay denied.", "maxLength": 253, "minLength": 1, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "title": "Destination hostname", "type": "string" }, "id": { "pattern": "^[a-z][a-z0-9-]{0,47}$", "title": "Rule ID", "type": "string" }, "ports": { "items": { "additionalProperties": false, "properties": { "from": { "maximum": 65535, "minimum": 1, "title": "Start port", "type": "integer" }, "to": { "maximum": 65535, "minimum": 1, "title": "End port", "type": "integer" } }, "required": ["from", "to"], "type": "object" }, "maxItems": 16, "minItems": 1, "title": "Port ranges", "type": "array" } }, "required": ["id", "binary", "host", "ports"], "type": "object" }, "maxItems": 32, "title": "Network rules", "type": "array" }, "configuration": { "additionalProperties": false, "properties": { "actions": { "additionalProperties": false, "properties": { "apply": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "read": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "save": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" }, "validate": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "href": { "maxLength": 2048, "pattern": "^/[^/]", "type": "string" }, "method": { "anyOf": [ { "const": "GET", "type": "string" }, { "const": "POST", "type": "string" }, { "const": "PUT", "type": "string" } ] } }, "required": ["method", "href", "available"], "type": "object" } }, "type": "object" }, "binding": { "anyOf": [ { "const": "installation-startup", "type": "string" }, { "const": "sandbox-policy", "type": "string" } ] }, "capability": { "type": "string" }, "configurationSchema": { "additionalProperties": {}, "type": "object" }, "driverId": { "type": "string" }, "implementation": { "type": "string" }, "key": { "type": "string" }, "scope": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "agent", "type": "string" } ] }, "startupConfiguration": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "type": "object" } }, "required": [ "capability", "driverId", "implementation", "scope", "key", "configurationSchema", "binding", "actions" ], "type": "object" }, "defaults": { "anyOf": [ { "type": "null" }, { "additionalProperties": {}, "type": "object" } ] }, "defaultsRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "deployedPolicyVersion": { "description": "The saved policy version the active revision (defaultsRevisionId) was deployed with. Its Sandbox enforces that version without a live application.", "maximum": 2147483647, "minimum": 1, "type": "integer" }, "editingEnabled": { "type": "boolean" }, "policy": { "additionalProperties": false, "properties": { "additions": { "items": { "additionalProperties": false, "properties": { "binary": { "description": "Absolute path of the executable receiving access.", "maxLength": 512, "minLength": 2, "pattern": "^/[^\\s\\x00-\\x1f]+$", "title": "Executable path", "type": "string" }, "host": { "description": "DNS hostname or permitted single-label wildcard. Grants allow access; omitted destinations stay denied.", "maxLength": 253, "minLength": 1, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "title": "Destination hostname", "type": "string" }, "id": { "pattern": "^[a-z][a-z0-9-]{0,47}$", "title": "Rule ID", "type": "string" }, "ports": { "items": { "additionalProperties": false, "properties": { "from": { "maximum": 65535, "minimum": 1, "title": "Start port", "type": "integer" }, "to": { "maximum": 65535, "minimum": 1, "title": "End port", "type": "integer" } }, "required": ["from", "to"], "type": "object" }, "maxItems": 16, "minItems": 1, "title": "Port ranges", "type": "array" } }, "required": ["id", "binary", "host", "ports"], "type": "object" }, "maxItems": 32, "title": "Network rules", "type": "array" }, "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "application": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "policyVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "providerVersion": { "type": "string" }, "reason": { "type": "string" }, "requestedAt": { "type": "string" }, "requestedBy": { "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "applied", "type": "string" }, { "const": "failed", "type": "string" } ] } }, "required": [ "id", "revisionId", "policyVersion", "state", "requestedBy", "requestedAt" ], "type": "object" }, "applied": { "additionalProperties": false, "properties": { "appliedAt": { "type": "string" }, "policyVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "providerVersion": { "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "revisionId", "policyVersion", "providerVersion", "appliedAt" ], "type": "object" }, "id": { "pattern": "^sbp_[0-9a-f-]{36}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "version": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["id", "namespaceId", "agentId", "version", "additions"], "type": "object" }, "protectedExecution": { "description": "True while the active revision or the next deploy runs under protected execution. Saving network policy additions is then refused with SANDBOX_POLICY_PROTECTED_EXECUTION; saving an empty policy stays allowed.", "type": "boolean" }, "unavailableReason": { "description": "Why per-Agent network policy is unavailable, when capability is null: the sentence the save, validate, apply and editing refusals give.", "type": "string" } }, "required": [ "policy", "editingEnabled", "protectedExecution", "ceiling", "defaults", "capability" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read one Agent sandbox policy and delegation ceiling", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" }, { "action": "read", "resourceKind": "sandbox_policy", "scope": "requested" } ] }, "put": { "description": "Requires manage_policy permission on the requested Agent. Requires update permission on the requested SandboxPolicy.", "operationId": "updateAgentSandboxPolicy", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "networking" } }, "in": "path", "name": "facet", "required": true, "schema": { "anyOf": [ { "const": "networking", "type": "string" }, { "const": "filesystem", "type": "string" }, { "const": "process", "type": "string" } ] } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "additions": [], "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "properties": { "additions": { "items": { "additionalProperties": false, "properties": { "binary": { "description": "Absolute path of the executable receiving access.", "maxLength": 512, "minLength": 2, "pattern": "^/[^\\s\\x00-\\x1f]+$", "title": "Executable path", "type": "string" }, "host": { "description": "DNS hostname or permitted single-label wildcard. Grants allow access; omitted destinations stay denied.", "maxLength": 253, "minLength": 1, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "title": "Destination hostname", "type": "string" }, "id": { "pattern": "^[a-z][a-z0-9-]{0,47}$", "title": "Rule ID", "type": "string" }, "ports": { "items": { "additionalProperties": false, "properties": { "from": { "maximum": 65535, "minimum": 1, "title": "Start port", "type": "integer" }, "to": { "maximum": 65535, "minimum": 1, "title": "End port", "type": "integer" } }, "required": ["from", "to"], "type": "object" }, "maxItems": 16, "minItems": 1, "title": "Port ranges", "type": "array" } }, "required": ["id", "binary", "host", "ports"], "type": "object" }, "maxItems": 32, "title": "Network rules", "type": "array" }, "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["expectedVersion", "additions"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "additions": [], "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "id": "sbp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "version": 2 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "additions": { "items": { "additionalProperties": false, "properties": { "binary": { "description": "Absolute path of the executable receiving access.", "maxLength": 512, "minLength": 2, "pattern": "^/[^\\s\\x00-\\x1f]+$", "title": "Executable path", "type": "string" }, "host": { "description": "DNS hostname or permitted single-label wildcard. Grants allow access; omitted destinations stay denied.", "maxLength": 253, "minLength": 1, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "title": "Destination hostname", "type": "string" }, "id": { "pattern": "^[a-z][a-z0-9-]{0,47}$", "title": "Rule ID", "type": "string" }, "ports": { "items": { "additionalProperties": false, "properties": { "from": { "maximum": 65535, "minimum": 1, "title": "Start port", "type": "integer" }, "to": { "maximum": 65535, "minimum": 1, "title": "End port", "type": "integer" } }, "required": ["from", "to"], "type": "object" }, "maxItems": 16, "minItems": 1, "title": "Port ranges", "type": "array" } }, "required": ["id", "binary", "host", "ports"], "type": "object" }, "maxItems": 32, "title": "Network rules", "type": "array" }, "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "application": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "policyVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "providerVersion": { "type": "string" }, "reason": { "type": "string" }, "requestedAt": { "type": "string" }, "requestedBy": { "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "applied", "type": "string" }, { "const": "failed", "type": "string" } ] } }, "required": [ "id", "revisionId", "policyVersion", "state", "requestedBy", "requestedAt" ], "type": "object" }, "applied": { "additionalProperties": false, "properties": { "appliedAt": { "type": "string" }, "policyVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "providerVersion": { "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "revisionId", "policyVersion", "providerVersion", "appliedAt" ], "type": "object" }, "id": { "pattern": "^sbp_[0-9a-f-]{36}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "version": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["id", "namespaceId", "agentId", "version", "additions"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Replace one Agent network policy additions", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "manage_policy", "resourceKind": "agent", "scope": "requested" }, { "action": "update", "resourceKind": "sandbox_policy", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/sandbox-policy/{facet}/apply": { "post": { "description": "Requires manage_policy permission on the requested Agent. Requires update permission on the requested SandboxPolicy. Requires read permission on the requested SandboxPolicy.", "operationId": "applyAgentSandboxPolicy", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "networking" } }, "in": "path", "name": "facet", "required": true, "schema": { "anyOf": [ { "const": "networking", "type": "string" }, { "const": "filesystem", "type": "string" }, { "const": "process", "type": "string" } ] } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedVersion": 1, "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000" } } }, "schema": { "additionalProperties": false, "properties": { "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["expectedVersion", "revisionId"], "type": "object" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "additions": [], "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "application": { "id": "123e4567-e89b-42d3-a456-426614174000", "policyVersion": 1, "requestedAt": "2026-10-01T12:00:00.000Z", "requestedBy": "principal-administrator", "revisionId": "rev_123e4567-e89b-42d3-a456-426614174000", "state": "pending" }, "id": "sbp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "version": 1 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "additions": { "items": { "additionalProperties": false, "properties": { "binary": { "description": "Absolute path of the executable receiving access.", "maxLength": 512, "minLength": 2, "pattern": "^/[^\\s\\x00-\\x1f]+$", "title": "Executable path", "type": "string" }, "host": { "description": "DNS hostname or permitted single-label wildcard. Grants allow access; omitted destinations stay denied.", "maxLength": 253, "minLength": 1, "pattern": "^(\\*\\.)?[a-z0-9]([a-z0-9.-]*[a-z0-9])?$", "title": "Destination hostname", "type": "string" }, "id": { "pattern": "^[a-z][a-z0-9-]{0,47}$", "title": "Rule ID", "type": "string" }, "ports": { "items": { "additionalProperties": false, "properties": { "from": { "maximum": 65535, "minimum": 1, "title": "Start port", "type": "integer" }, "to": { "maximum": 65535, "minimum": 1, "title": "End port", "type": "integer" } }, "required": ["from", "to"], "type": "object" }, "maxItems": 16, "minItems": 1, "title": "Port ranges", "type": "array" } }, "required": ["id", "binary", "host", "ports"], "type": "object" }, "maxItems": 32, "title": "Network rules", "type": "array" }, "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "application": { "additionalProperties": false, "properties": { "id": { "format": "uuid", "type": "string" }, "policyVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "providerVersion": { "type": "string" }, "reason": { "type": "string" }, "requestedAt": { "type": "string" }, "requestedBy": { "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "applied", "type": "string" }, { "const": "failed", "type": "string" } ] } }, "required": [ "id", "revisionId", "policyVersion", "state", "requestedBy", "requestedAt" ], "type": "object" }, "applied": { "additionalProperties": false, "properties": { "appliedAt": { "type": "string" }, "policyVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" }, "providerVersion": { "type": "string" }, "revisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": [ "revisionId", "policyVersion", "providerVersion", "appliedAt" ], "type": "object" }, "id": { "pattern": "^sbp_[0-9a-f-]{36}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "version": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["id", "namespaceId", "agentId", "version", "additions"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Apply the saved policy to the running Agent revision", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "manage_policy", "resourceKind": "agent", "scope": "requested" }, { "action": "update", "resourceKind": "sandbox_policy", "scope": "requested" }, { "action": "read", "resourceKind": "sandbox_policy", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/sandbox-policy/{facet}/editing": { "patch": { "description": "Requires administer permission on the requested Agent. Requires administer permission for Installation resources in the Installation.", "operationId": "TEMPORARY_API_WILL_BREAK_IN_FUTURE_setAgentSandboxPolicyEditing", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "networking" } }, "in": "path", "name": "facet", "required": true, "schema": { "anyOf": [ { "const": "networking", "type": "string" }, { "const": "filesystem", "type": "string" }, { "const": "process", "type": "string" } ] } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "enabled": true } } }, "schema": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" } }, "required": ["enabled"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "backendId": null, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "desiredRuntimeState": "stopped", "executionMode": "dedicated", "gatewayManagedMode": true, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "agt_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent", "status": "active" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "pluginDriver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "harnessAuth", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Temporarily enable or disable future policy edits for one Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "agent", "scope": "requested" }, { "action": "administer", "resourceKind": "installation", "scope": "installation" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/sandbox-policy/{facet}/validate": { "post": { "description": "Requires manage_policy permission on the requested Agent.", "operationId": "validateAgentSandboxPolicy", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "networking" } }, "in": "path", "name": "facet", "required": true, "schema": { "anyOf": [ { "const": "networking", "type": "string" }, { "const": "filesystem", "type": "string" }, { "const": "process", "type": "string" } ] } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "additions": [], "expectedVersion": 1 } } }, "schema": { "additionalProperties": false, "properties": { "additions": {}, "expectedVersion": { "maximum": 2147483647, "minimum": 1, "type": "integer" } }, "required": ["expectedVersion", "additions"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "data": [], "success": true }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": false, "properties": { "data": {}, "success": { "const": true, "type": "boolean" } }, "required": ["success", "data"], "type": "object" }, { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "details": { "items": { "additionalProperties": false, "properties": { "code": { "anyOf": [ { "const": "REQUIRED", "type": "string" }, { "const": "UNKNOWN_FIELD", "type": "string" }, { "const": "INVALID_TYPE", "type": "string" }, { "const": "INVALID_FORMAT", "type": "string" }, { "const": "INVALID_VALUE", "type": "string" }, { "const": "TOO_LONG", "type": "string" }, { "const": "TOO_DEEP", "type": "string" }, { "const": "INVALID_RANGE", "type": "string" }, { "const": "OUTSIDE_CEILING", "type": "string" } ] }, "message": { "maxLength": 512, "type": "string" }, "path": { "maxLength": 512, "pattern": "^(?:/(?:[^~/]|~0|~1)*)*$", "type": "string" } }, "required": ["path", "code"], "type": "object" }, "maxItems": 32, "minItems": 1, "type": "array" } }, "required": ["details"], "type": "object" }, "success": { "const": false, "type": "boolean" } }, "required": ["success", "error"], "type": "object" } ] }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Preview Agent network policy admission without saving or applying", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "manage_policy", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/stop": { "post": { "description": "Requires operate permission on the requested Agent.", "operationId": "stopAgent", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "backendId": null, "configurationId": "cfg_123e4567-e89b-42d3-a456-426614174000", "createdAt": "2026-10-01T12:00:00.000Z", "desiredRuntimeState": "stopped", "executionMode": "dedicated", "gatewayManagedMode": true, "harnessAuth": { "method": "api_key", "source": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "id": "agt_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "servicePrincipalId": "principal-docs-agent", "status": "active" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "activeRevisionId": { "pattern": "^rev_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "backendId": { "anyOf": [ { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, { "type": "null" } ] }, "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "credentialSources": { "description": "Every credential source the Agent uses, at each source's endpoints. A credential-source harnessAuth names one entry. The selected Credential Gateway injects them at deployment; the Agent never receives their values.", "items": { "additionalProperties": false, "properties": { "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["sourceId"], "type": "object" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "desiredRuntimeState": { "anyOf": [ { "const": "running", "type": "string" }, { "const": "stopped", "type": "string" } ] }, "executionMode": { "anyOf": [ { "const": "embedded", "type": "string" }, { "const": "dedicated", "type": "string" } ] }, "gatewayManagedMode": { "description": "Whether OCE restricts Gateway-local administration. Defaults on when the selected Compute Driver supports it, otherwise off. Changing the setting requires Installation administer permission and takes effect on deployment.", "type": "boolean" }, "harnessAuth": { "anyOf": [ { "anyOf": [ { "additionalProperties": false, "properties": { "method": { "const": "runtime", "type": "string" } }, "required": ["method"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "api_key", "type": "string" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "codex_pat", "type": "string" }, "source": { "anyOf": [ { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "service_account", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } ] } }, "required": ["method", "source"], "type": "object" }, { "additionalProperties": false, "properties": { "method": { "const": "credential_source", "type": "string" }, "sourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["method", "sourceId"], "type": "object" } ] }, { "type": "null" } ] }, "id": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "pluginApprovers": { "$ref": "#/components/schemas/def-2" }, "pluginDriver": { "$ref": "#/components/schemas/def-1" }, "plugins": { "$ref": "#/components/schemas/def-6" }, "repositoryAccess": { "additionalProperties": false, "description": "Desired repository access. Each omitted repository profile inherits defaultProfile; explicit profiles remain overrides. Mutually exclusive with repositoryBindings in create, provision, and update requests.", "properties": { "defaultProfile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositories": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef"], "type": "object" }, "maxItems": 16, "type": "array" } }, "required": ["defaultProfile", "repositories"], "type": "object" }, "repositoryBindings": { "items": { "additionalProperties": false, "properties": { "profile": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" }, "repositoryRef": { "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$", "type": "string" } }, "required": ["repositoryRef", "profile"], "type": "object" }, "maxItems": 16, "minItems": 1, "type": "array" }, "sandboxPolicyEditing": { "type": "boolean" }, "servicePrincipalId": { "maxLength": 200, "minLength": 1, "type": "string" }, "status": { "anyOf": [ { "const": "active", "type": "string" }, { "const": "deleting", "type": "string" } ] } }, "required": [ "id", "namespaceId", "name", "servicePrincipalId", "configurationId", "backendId", "harnessAuth", "executionMode", "gatewayManagedMode", "desiredRuntimeState", "status", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Stop one Agent and keep its saved Agent revision and persistent state", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/agents/{agentId}/workspace/files/{name}": { "get": { "description": "Requires read permission on the requested Agent.", "operationId": "getAgentWorkspaceFile", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "AGENTS.md" } }, "in": "path", "name": "name", "required": true, "schema": { "enum": ["AGENTS.md", "SOUL.md", "IDENTITY.md", "USER.md"] } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "content": "Explain your changes and verify the affected behavior.\n", "name": "AGENTS.md" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "content": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "name": { "enum": ["AGENTS.md", "SOUL.md", "IDENTITY.md", "USER.md"] } }, "required": ["name", "content"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Conflict. The Agent has no running version: deploy it, or wait until its deployment finishes." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read an allowed workspace file from one active Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "agent", "scope": "requested" } ] }, "put": { "description": "Requires operate permission on the requested Agent.", "operationId": "putAgentWorkspaceFile", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "agt_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "agentId", "required": true, "schema": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "AGENTS.md" } }, "in": "path", "name": "name", "required": true, "schema": { "enum": ["AGENTS.md", "SOUL.md", "IDENTITY.md", "USER.md"] } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "content": "Explain your changes and verify the affected behavior.\n" } } }, "schema": { "additionalProperties": false, "properties": { "content": { "description": "Workspace file content. The controller also enforces a 16 KiB UTF-8 byte limit and rejects unpaired UTF-16 surrogates.", "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "required": ["content"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "name": "AGENTS.md", "size": 54 }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "name": { "enum": ["AGENTS.md", "SOUL.md", "IDENTITY.md", "USER.md"] }, "size": { "maximum": 16384, "minimum": 0, "type": "integer" } }, "required": ["name"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Service Unavailable. Check `error.code`: `DEPENDENCY_UNAVAILABLE` means workspace access is unavailable. `UNKNOWN_OUTCOME` means OCC could not confirm the write or its audit record; the file may already contain the requested content. Read the same file with `GET` and compare its content before deciding whether to retry. If the content matches, do not retry. If you cannot read it, wait or ask someone with `read` permission on the Agent to check." } }, "summary": "Create or replace an allowed workspace file for one active Agent", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "resourceKind": "agent", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/channel-directory/lookup": { "post": { "description": "Requires operate permission on the exact Secret named by secretId. Without an edit target, requires Agent create permission in the Namespace. With agentId, requires update permission on that exact Agent. With configurationId, requires update permission on that exact Configuration.", "operationId": "lookupChannelDirectory", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "kind": "channels", "query": "engineering", "secretId": "sec_123e4567-e89b-42d3-a456-426614174000" } } }, "schema": { "anyOf": [ { "additionalProperties": false, "properties": { "cursor": { "maxLength": 2048, "minLength": 1, "pattern": "^[^\\u0000]*$", "type": "string" }, "kind": { "anyOf": [ { "const": "users", "type": "string" }, { "const": "channels", "type": "string" } ] }, "query": { "maxLength": 200, "pattern": "^[^\\u0000]*$", "type": "string" }, "secretId": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["secretId", "kind"], "type": "object" }, { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "cursor": { "maxLength": 2048, "minLength": 1, "pattern": "^[^\\u0000]*$", "type": "string" }, "kind": { "anyOf": [ { "const": "users", "type": "string" }, { "const": "channels", "type": "string" } ] }, "query": { "maxLength": 200, "pattern": "^[^\\u0000]*$", "type": "string" }, "secretId": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["secretId", "kind", "agentId"], "type": "object" }, { "additionalProperties": false, "properties": { "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "cursor": { "maxLength": 2048, "minLength": 1, "pattern": "^[^\\u0000]*$", "type": "string" }, "kind": { "anyOf": [ { "const": "users", "type": "string" }, { "const": "channels", "type": "string" } ] }, "query": { "maxLength": 200, "pattern": "^[^\\u0000]*$", "type": "string" }, "secretId": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["secretId", "kind", "configurationId"], "type": "object" }, { "additionalProperties": false, "properties": { "ids": { "items": { "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array", "uniqueItems": true }, "kind": { "anyOf": [ { "const": "users", "type": "string" }, { "const": "channels", "type": "string" } ] }, "secretId": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["secretId", "kind", "ids"], "type": "object" }, { "additionalProperties": false, "properties": { "agentId": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "ids": { "items": { "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array", "uniqueItems": true }, "kind": { "anyOf": [ { "const": "users", "type": "string" }, { "const": "channels", "type": "string" } ] }, "secretId": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["secretId", "kind", "ids", "agentId"], "type": "object" }, { "additionalProperties": false, "properties": { "configurationId": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "ids": { "items": { "maxLength": 200, "minLength": 1, "pattern": "^[^\\u0000-\\u001f\\u007f]+$", "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array", "uniqueItems": true }, "kind": { "anyOf": [ { "const": "users", "type": "string" }, { "const": "channels", "type": "string" } ] }, "secretId": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["secretId", "kind", "ids", "configurationId"], "type": "object" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "candidates": [{ "id": "C0123456789", "name": "engineering" }], "complete": true, "workspaceId": "T0123456789", "workspaceName": "Engineering" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "candidates": { "items": { "additionalProperties": false, "properties": { "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["id", "name"], "type": "object" }, "maxItems": 100, "type": "array" }, "complete": { "type": "boolean" }, "nextCursor": { "maxLength": 2048, "minLength": 1, "type": "string" }, "workspaceId": { "maxLength": 200, "minLength": 1, "type": "string" }, "workspaceName": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["workspaceId", "candidates", "complete"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/CHANNEL_DIRECTORY_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests. Wait for Retry-After and try again." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Search a channel directory using an authorized Namespace Secret", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "condition": "directory_lookup", "resourceKind": "secret", "scope": "request_body" }, { "action": "create", "condition": "directory_lookup", "resourceKind": "agent", "scope": "namespace" }, { "action": "update", "condition": "directory_lookup", "resourceKind": "agent", "scope": "request_body" }, { "action": "update", "condition": "directory_lookup", "resourceKind": "configuration", "scope": "request_body" } ] } }, "/namespaces/{namespaceId}/configurations": { "post": { "description": "Requires create permission for Configuration resources in the requested Namespace. Requires operate permission on each Secret supplied in request body Secret bindings.", "operationId": "createConfiguration", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "kind": "agent", "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } } } }, "schema": { "additionalProperties": false, "properties": { "kind": { "const": "agent", "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "required": ["kind", "values"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "generation": 1, "id": "cfg_123e4567-e89b-42d3-a456-426614174000", "kind": "agent", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "generation": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "id": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "agent", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "required": [ "id", "namespaceId", "kind", "generation", "values", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create a native Namespace-owned Agent Configuration", "tags": ["Configurations"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "configuration", "scope": "namespace" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "request_body" } ] } }, "/namespaces/{namespaceId}/configurations/{configurationId}": { "delete": { "description": "Requires delete permission on the requested Configuration.", "operationId": "deleteConfiguration", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cfg_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "configurationId", "required": true, "schema": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete an exact unreferenced Namespace-owned Configuration", "tags": ["Configurations"], "x-openclaw-permissions": [ { "action": "delete", "resourceKind": "configuration", "scope": "requested" } ] }, "get": { "description": "Requires read permission on the requested Configuration.", "operationId": "getConfiguration", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cfg_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "configurationId", "required": true, "schema": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "generation": 1, "id": "cfg_123e4567-e89b-42d3-a456-426614174000", "kind": "agent", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "generation": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "id": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "agent", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "required": [ "id", "namespaceId", "kind", "generation", "values", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an exact Namespace-owned Configuration", "tags": ["Configurations"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "configuration", "scope": "requested" } ] }, "patch": { "description": "Requires update permission on the requested Configuration. Requires operate permission on each Secret bound by the resulting Configuration.", "operationId": "updateConfiguration", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cfg_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "configurationId", "required": true, "schema": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "expectedGeneration": 1, "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } } } }, "schema": { "additionalProperties": false, "properties": { "expectedGeneration": { "description": "The generation this update replaces, from the caller's last read. A Configuration at another generation refuses the update with 409 and an `/expectedGeneration` detail, and keeps its content. Omitted, the update replaces whatever generation is current.", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "required": ["values"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "generation": 2, "id": "cfg_123e4567-e89b-42d3-a456-426614174000", "kind": "agent", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "generation": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "id": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "agent", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "secretBindings": { "additionalProperties": { "additionalProperties": false, "description": "Maps one destination environment variable to one exact Secret reference. Optional `delivery` defaults to `{ \"type\": \"env\" }` during admission.", "properties": { "delivery": { "additionalProperties": false, "description": "Gateway delivery mode. Only `{ \"type\": \"env\" }` is supported.", "properties": { "type": { "const": "env", "type": "string" } }, "required": ["type"], "type": "object" }, "source": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["source"], "type": "object" }, "description": "Optional Secret binding map. Keys are destination environment variable names; at most 64 bindings are accepted. Each value must contain `source.kind`, `source.namespaceId`, and `source.id`, and may contain `delivery.type: \"env\"`. Admission rejects reserved or process-control destinations such as `OPENCLAW_*`, `CODEX_*`, `OPENAI_*`, `ANTHROPIC_*`, `OCC_*`, `KUBERNETES_*`, `PATH`, `HOME`, and proxy variables. Model authentication belongs to Agent.harnessAuth.", "maxProperties": 64, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "required": [ "id", "namespaceId", "kind", "generation", "values", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Replace values and increment an exact Namespace-owned Configuration generation", "tags": ["Configurations"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "configuration", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/connection-templates": { "get": { "description": "Requires create permission for CredentialSource resources in the requested Namespace.", "operationId": "listUsableConnectionTemplates", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "createdAt": "2026-10-01T12:00:00.000Z", "current": { "authorizationParameters": {}, "authorizationUrl": "https://accounts.example.com/authorize", "createdAt": "2026-10-01T12:00:00.000Z", "destinations": [ { "host": "api.example.com", "path": "/profile", "port": 443 } ], "issuer": "https://accounts.example.com", "mode": "manual", "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000", "scopes": ["profile.read"], "templateId": "ctp_123e4567-e89b-42d3-a456-426614174000", "tokenUrl": "https://accounts.example.com/token", "version": 1 }, "displayName": "Example account", "id": "ctp_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/def-15" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List connection templates the caller may connect in this Namespace", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "credential_source", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/connections": { "get": { "description": "Requires read permission on the requested Namespace. Only CredentialSource resources with individual read permission are returned.", "operationId": "listNamespaceConnections", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "clientId": "example-client", "connectionTemplateId": "ctp_123e4567-e89b-42d3-a456-426614174000", "connectionTemplateVersion": 1, "createdAt": "2026-10-01T12:00:00.000Z", "credentialSourceId": "cs_123e4567-e89b-42d3-a456-426614174000", "destinations": [ { "host": "api.example.com", "path": "/profile", "port": 443 } ], "grantedScopes": ["profile.read"], "issuer": "https://accounts.example.com", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "oauthClientId": "ccr_123e4567-e89b-42d3-a456-426614174000", "ownerPrincipalId": "user-docs-admin", "requestedScopes": ["profile.read"], "tokenUrl": "https://accounts.example.com/token" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "clientId": { "type": "string" }, "connectionTemplateId": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "connectionTemplateVersion": { "minimum": 1, "type": "integer" }, "createdAt": { "type": "string" }, "credentialSourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "destinations": { "description": "Effective credential delivery destinations; empty when the current template is unavailable or incompatible.", "items": { "additionalProperties": false, "properties": { "host": { "type": "string" }, "path": { "type": "string" }, "port": { "type": "integer" } }, "required": ["host", "port", "path"], "type": "object" }, "type": "array" }, "grantedScopes": { "items": { "type": "string" }, "type": "array" }, "issuer": { "type": "string" }, "mcpServerUrl": { "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "oauthClientId": { "type": "string" }, "ownerPrincipalId": { "type": "string" }, "requestedScopes": { "items": { "type": "string" }, "type": "array" }, "resource": { "type": "string" }, "tokenUrl": { "type": "string" } }, "required": [ "namespaceId", "credentialSourceId", "ownerPrincipalId", "tokenUrl", "oauthClientId", "clientId", "issuer", "destinations", "requestedScopes", "grantedScopes", "connectionTemplateId", "connectionTemplateVersion", "createdAt" ], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List completed connections the caller can read in this Namespace", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" }, { "action": "read", "resourceKind": "credential_source", "scope": "each_returned" } ] }, "post": { "description": "Requires create permission for CredentialSource resources in the requested Namespace.", "operationId": "startNamespaceConnection", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "connectionTemplateId": "ctp_123e4567-e89b-42d3-a456-426614174000" } } }, "schema": { "additionalProperties": false, "properties": { "connectionTemplateId": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "selectedScopes": { "items": { "maxLength": 512, "minLength": 1, "pattern": "^[\\x21\\x23-\\x5b\\x5d-\\x7e]+$", "type": "string" }, "type": "array", "uniqueItems": true } }, "required": ["connectionTemplateId"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "authorizationUrl": "https://accounts.example.com/authorize?state=example-state", "credentialSourceId": "cs_123e4567-e89b-42d3-a456-426614174000", "expiresAt": "2026-10-01T12:00:00.000Z" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "authorizationUrl": { "type": "string" }, "credentialSourceId": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "expiresAt": { "type": "string" } }, "required": ["credentialSourceId", "authorizationUrl", "expiresAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "501": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_IMPLEMENTED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The selected Driver does not support this operation." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Start consent for a reusable account in this Namespace", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "credential_source", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/connections/{credentialSourceId}": { "delete": { "description": "Requires delete permission on this CredentialSource unless the caller owns the saved connection.", "operationId": "disconnectNamespaceConnection", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cs_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "credentialSourceId", "required": true, "schema": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Disconnect a saved account and retire its OAuth grant", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "delete", "condition": "unless_consent_owner", "resourceKind": "credential_source", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/credential-sources": { "get": { "description": "Requires read permission on the requested Namespace. Only CredentialSource resources with individual read permission are returned.", "operationId": "listCredentialSources", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "config": {}, "id": "cs_123e4567-e89b-42d3-a456-426614174000", "name": "Model credentials", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ownerCapability": "credential_gateway", "ref": { "id": "cs_123e4567-e89b-42d3-a456-426614174000", "kind": "credential_source", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "secrets": { "api_key": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "state": "ready", "type": "openai" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "config": { "additionalProperties": { "maxLength": 2048, "minLength": 1, "type": "string" }, "description": "Non-secret source configuration keyed by catalog field name.", "maxProperties": 32, "type": "object" }, "egress": { "additionalProperties": false, "description": "Protected live static, eligible prepared, or explicitly credential-free metadata access. Each profile requires its own grant; missing material never selects credential-free access. Runtime readiness requires current authenticated supervisor evidence.", "properties": { "adoption": { "anyOf": [ { "const": "live", "type": "string" }, { "const": "prepared", "type": "string" }, { "const": "credential_free", "type": "string" } ] }, "retention": { "const": "none", "type": "string" } }, "required": ["adoption", "retention"], "type": "object" }, "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "ownerCapability": { "anyOf": [ { "const": "credential_gateway", "type": "string" }, { "const": "credential_proxy", "type": "string" }, { "const": "token_service", "type": "string" } ], "description": "The Token Service owns saved accounts. Other sources belong to the Driver that admitted them." }, "ref": { "additionalProperties": false, "description": "Exact OCC credential source reference. Shape: `{ \"kind\": \"credential_source\", \"namespaceId\": \"ns_...\", \"id\": \"cs_...\" }`.", "properties": { "id": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "credential_source", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "secrets": { "additionalProperties": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "description": "Secret inputs keyed by catalog field name. Each value references an OCC Secret in the same Namespace; OCC never returns its value.", "maxProperties": 16, "type": "object" }, "state": { "anyOf": [ { "const": "registering", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "deleting", "type": "string" } ] }, "status": { "additionalProperties": false, "description": "Source admission or selected Credential Gateway status. For protected sources, ready does not attest an installed enforcing Sandbox; current supervisor evidence is checked separately. Never contains credential values.", "properties": { "reason": { "maxLength": 512, "type": "string" }, "refresh": { "additionalProperties": false, "description": "Token refresh status reported by the selected Credential Refresh Driver for a refresh-type source. It never contains tokens or refresh material.", "properties": { "expiresAt": { "format": "date-time", "type": "string" }, "failureCode": { "maxLength": 128, "type": "string" }, "lastRefreshAt": { "format": "date-time", "type": "string" }, "nextRefreshAt": { "format": "date-time", "type": "string" }, "recoveryAction": { "anyOf": [ { "const": "retry", "type": "string" }, { "const": "reauthorize", "type": "string" }, { "const": "fix_configuration", "type": "string" }, { "const": "investigate", "type": "string" } ] }, "state": { "anyOf": [ { "const": "pending", "type": "string" }, { "const": "ready", "type": "string" }, { "const": "failed", "type": "string" } ] } }, "required": ["state"], "type": "object" }, "state": { "anyOf": [ { "const": "ready", "type": "string" }, { "const": "pending", "type": "string" }, { "const": "failed", "type": "string" }, { "const": "absent", "type": "string" } ] } }, "required": ["state"], "type": "object" }, "type": { "description": "Source type from the selected Credential Gateway catalog, for example `openai`.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9-]{0,63}$", "type": "string" } }, "required": [ "id", "namespaceId", "name", "type", "ownerCapability", "config", "secrets", "state", "ref" ], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List readable credential sources without revealing credential values", "tags": ["Credential sources"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" }, { "action": "read", "resourceKind": "credential_source", "scope": "each_returned" } ] }, "post": { "description": "Requires create permission for CredentialSource resources in the requested Namespace. Requires operate permission on each Secret named in the request body secrets.", "operationId": "createCredentialSource", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "config": {}, "name": "Model credentials", "secrets": { "api_key": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "type": "openai" } } }, "schema": { "additionalProperties": false, "properties": { "config": { "additionalProperties": { "maxLength": 2048, "minLength": 1, "type": "string" }, "description": "Non-secret source configuration keyed by catalog field name.", "maxProperties": 32, "type": "object" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "secrets": { "additionalProperties": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "description": "Secret inputs keyed by catalog field name. Each value references an OCC Secret in the same Namespace; OCC never returns its value.", "maxProperties": 16, "type": "object" }, "type": { "description": "Source type from the selected Credential Gateway catalog, for example `openai`.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9-]{0,63}$", "type": "string" } }, "required": ["name", "type"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "config": {}, "id": "cs_123e4567-e89b-42d3-a456-426614174000", "name": "Model credentials", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ownerCapability": "credential_gateway", "ref": { "id": "cs_123e4567-e89b-42d3-a456-426614174000", "kind": "credential_source", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "secrets": { "api_key": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "state": "ready", "type": "openai" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "$ref": "#/components/schemas/def-13" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Register a credential source with the selected Credential Gateway", "tags": ["Credential sources"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "credential_source", "scope": "namespace" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "request_body" } ] } }, "/namespaces/{namespaceId}/credential-sources/{credentialSourceId}": { "delete": { "description": "Requires delete permission on the requested CredentialSource.", "operationId": "deleteCredentialSource", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cs_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "credentialSourceId", "required": true, "schema": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "allOf": [{ "$ref": "#/components/schemas/def-7" }] } } }, "description": "A required dependency is unavailable.", "headers": { "Retry-After": { "description": "Whole seconds before retrying DELETE when error.reason is credential_registration_pending. Absent for other dependency failures.", "schema": { "pattern": "^[1-9][0-9]*$", "type": "string" } } } } }, "summary": "Remove an unreferenced credential source from the Credential Gateway", "tags": ["Credential sources"], "x-openclaw-permissions": [ { "action": "delete", "resourceKind": "credential_source", "scope": "requested" } ] }, "get": { "description": "Requires read permission on the requested CredentialSource.", "operationId": "getCredentialSource", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cs_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "credentialSourceId", "required": true, "schema": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "config": {}, "id": "cs_123e4567-e89b-42d3-a456-426614174000", "name": "Model credentials", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ownerCapability": "credential_gateway", "ref": { "id": "cs_123e4567-e89b-42d3-a456-426614174000", "kind": "credential_source", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "secrets": { "api_key": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "state": "ready", "type": "openai" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "$ref": "#/components/schemas/def-13" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get one credential source and its live Credential Gateway status", "tags": ["Credential sources"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "credential_source", "scope": "requested" } ] }, "patch": { "description": "Requires update permission on the requested CredentialSource. Requires operate permission on each Secret the source references after the update, including its current references when the request omits secrets.", "operationId": "updateCredentialSource", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cs_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "credentialSourceId", "required": true, "schema": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "adoption": "live", "secrets": { "api_key": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } } } } }, "schema": { "additionalProperties": false, "description": "For a legacy source, omitting adoption and authorityScope updates the Credential Gateway copy. To admit an unbound legacy or narrower source for protected per-operation reads, send adoption: live and authorityScope: execution together. Existing approvals never expand because of an upgrade or a Secret change. Already-admitted sources remain live. PATCH requires an unbound source. A refresh token field (`refresh_token` of `oauth2-refresh-token`) must reference a new Secret. Non-secret config is immutable.", "properties": { "adoption": { "const": "live", "description": "Opt an unbound static source into protected live Secret reads. A legacy or narrower source also requires explicit authorityScope: execution. Requires source update and Secret operate permission.", "type": "string" }, "authorityScope": { "const": "execution", "description": "Consent to every process in this dedicated execution using the constrained inference grant. An older executable-specific grant is never broadened by an upgrade or Secret change.", "type": "string" }, "secrets": { "additionalProperties": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" }, "description": "Secret inputs keyed by catalog field name. Each value references an OCC Secret in the same Namespace; OCC never returns its value.", "maxProperties": 16, "type": "object" } }, "type": "object" } } }, "description": "For a legacy source, omitting adoption and authorityScope updates the Credential Gateway copy. To admit an unbound legacy or narrower source for protected per-operation reads, send adoption: live and authorityScope: execution together. Existing approvals never expand because of an upgrade or a Secret change. Already-admitted sources remain live. PATCH requires an unbound source. A refresh token field (`refresh_token` of `oauth2-refresh-token`) must reference a new Secret. Non-secret config is immutable.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "config": {}, "id": "cs_123e4567-e89b-42d3-a456-426614174000", "name": "Model credentials", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ownerCapability": "credential_gateway", "ref": { "id": "cs_123e4567-e89b-42d3-a456-426614174000", "kind": "credential_source", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "secrets": { "api_key": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "state": "ready", "type": "openai" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "$ref": "#/components/schemas/def-13" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Push current or replacement Secret values to the Credential Gateway copy", "tags": ["Credential sources"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "credential_source", "scope": "requested" }, { "action": "operate", "condition": "bound_secret", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/credential-sources/{credentialSourceId}/rotate": { "post": { "description": "Requires update permission on the requested CredentialSource.", "operationId": "rotateCredentialSource", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "cs_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "credentialSourceId", "required": true, "schema": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "config": {}, "id": "cs_123e4567-e89b-42d3-a456-426614174000", "name": "Model credentials", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ownerCapability": "credential_gateway", "ref": { "id": "cs_123e4567-e89b-42d3-a456-426614174000", "kind": "credential_source", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "secrets": { "api_key": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "state": "ready", "type": "openai" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "$ref": "#/components/schemas/def-13" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Force the Credential Refresh Driver to mint a new token for a refresh-type source", "tags": ["Credential sources"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "credential_source", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/iam/access-bindings": { "get": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "listIAMAccessBindings", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "id": "binding-agent-secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "resourceId": "sec_123e4567-e89b-42d3-a456-426614174000", "resourceKind": "secret", "roleId": "role-secret-operator", "subjectId": "principal-docs-agent", "subjectKind": "identity" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectKind": { "anyOf": [ { "const": "identity", "type": "string" }, { "const": "group", "type": "string" } ] } }, "required": ["id", "namespaceId", "subjectKind", "subjectId", "roleId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "resourceId": { "maxLength": 200, "minLength": 1, "type": "string" }, "resourceKind": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "namespace", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "service_account", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" } ] }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectKind": { "anyOf": [ { "const": "identity", "type": "string" }, { "const": "group", "type": "string" } ] } }, "required": [ "id", "namespaceId", "subjectKind", "subjectId", "roleId", "resourceKind", "resourceId" ], "type": "object" } ] }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List exact Namespace IAM AccessBindings", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] }, "post": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace. Requires read permission on the request body Agent when the AccessBinding targets that resource kind. Requires read permission on the request body Agent revision when the AccessBinding targets that resource kind. Requires read permission on the request body Configuration when the AccessBinding targets that resource kind. Requires read permission on the request body CredentialSource when the AccessBinding targets that resource kind. Requires read permission on the request body Namespace when the AccessBinding targets that resource kind. Requires read permission on the request body Preset when the AccessBinding targets that resource kind. Requires read permission on the request body Secret when the AccessBinding targets that resource kind. Requires read permission on the request body ServiceAccount when the AccessBinding targets that resource kind.", "operationId": "createIAMAccessBinding", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "resourceId": "sec_123e4567-e89b-42d3-a456-426614174000", "resourceKind": "secret", "roleId": "role-secret-operator", "subjectId": "principal-docs-agent", "subjectKind": "identity" } } }, "schema": { "additionalProperties": false, "properties": { "resourceId": { "maxLength": 200, "minLength": 1, "type": "string" }, "resourceKind": { "anyOf": [ { "const": "namespace", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "service_account", "type": "string" } ] }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectKind": { "const": "identity", "type": "string" } }, "required": ["subjectKind", "subjectId", "roleId", "resourceKind", "resourceId"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "binding-agent-secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "resourceId": "sec_123e4567-e89b-42d3-a456-426614174000", "resourceKind": "secret", "roleId": "role-secret-operator", "subjectId": "principal-docs-agent", "subjectKind": "identity" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectKind": { "anyOf": [ { "const": "identity", "type": "string" }, { "const": "group", "type": "string" } ] } }, "required": ["id", "namespaceId", "subjectKind", "subjectId", "roleId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "resourceId": { "maxLength": 200, "minLength": 1, "type": "string" }, "resourceKind": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "namespace", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "service_account", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" } ] }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectKind": { "anyOf": [ { "const": "identity", "type": "string" }, { "const": "group", "type": "string" } ] } }, "required": [ "id", "namespaceId", "subjectKind", "subjectId", "roleId", "resourceKind", "resourceId" ], "type": "object" } ] }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create an immutable exact-resource Namespace IAM AccessBinding", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "agent", "scope": "request_body" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "agent_revision", "scope": "request_body" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "configuration", "scope": "request_body" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "credential_source", "scope": "request_body" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "namespace", "scope": "request_body" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "preset", "scope": "request_body" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "secret", "scope": "request_body" }, { "action": "read", "condition": "iam_binding_target", "resourceKind": "service_account", "scope": "request_body" } ] } }, "/namespaces/{namespaceId}/iam/access-bindings/{bindingId}": { "delete": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "deleteIAMAccessBinding", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "binding-agent-secret" } }, "in": "path", "name": "bindingId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete one exact Namespace IAM AccessBinding", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] }, "get": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "getIAMAccessBinding", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "binding-agent-secret" } }, "in": "path", "name": "bindingId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "binding-agent-secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "resourceId": "sec_123e4567-e89b-42d3-a456-426614174000", "resourceKind": "secret", "roleId": "role-secret-operator", "subjectId": "principal-docs-agent", "subjectKind": "identity" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "anyOf": [ { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectKind": { "anyOf": [ { "const": "identity", "type": "string" }, { "const": "group", "type": "string" } ] } }, "required": ["id", "namespaceId", "subjectKind", "subjectId", "roleId"], "type": "object" }, { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "resourceId": { "maxLength": 200, "minLength": 1, "type": "string" }, "resourceKind": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "namespace", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "service_account", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" } ] }, "roleId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectId": { "maxLength": 200, "minLength": 1, "type": "string" }, "subjectKind": { "anyOf": [ { "const": "identity", "type": "string" }, { "const": "group", "type": "string" } ] } }, "required": [ "id", "namespaceId", "subjectKind", "subjectId", "roleId", "resourceKind", "resourceId" ], "type": "object" } ] }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an exact Namespace IAM AccessBinding", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/iam/roles": { "get": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "listIAMRoles", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "id": "role-secret-operator", "name": "Secret operator", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "permissions": [{ "action": "operate", "resourceKind": "secret" }] } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "permissions": { "items": { "additionalProperties": false, "properties": { "action": { "anyOf": [ { "const": "create", "type": "string" }, { "const": "read", "type": "string" }, { "const": "update", "type": "string" }, { "const": "delete", "type": "string" }, { "const": "deploy", "type": "string" }, { "const": "operate", "type": "string" }, { "const": "administer", "type": "string" }, { "const": "read_logs", "type": "string" }, { "const": "manage_policy", "type": "string" } ] }, "resourceKind": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "namespace", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "service_account", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" } ] } }, "required": ["action", "resourceKind"], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array" } }, "required": ["id", "namespaceId", "permissions"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List exact Namespace IAM Roles", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] }, "post": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "createIAMRole", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "name": "Secret operator", "permissions": [{ "action": "operate", "resourceKind": "secret" }] } } }, "schema": { "additionalProperties": false, "properties": { "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "permissions": { "items": { "additionalProperties": false, "properties": { "action": { "anyOf": [ { "const": "create", "type": "string" }, { "const": "read", "type": "string" }, { "const": "update", "type": "string" }, { "const": "delete", "type": "string" }, { "const": "deploy", "type": "string" }, { "const": "operate", "type": "string" }, { "const": "administer", "type": "string" }, { "const": "read_logs", "type": "string" }, { "const": "manage_policy", "type": "string" } ] }, "resourceKind": { "anyOf": [ { "const": "namespace", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "service_account", "type": "string" } ] } }, "required": ["action", "resourceKind"], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array" } }, "required": ["permissions"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "role-secret-operator", "name": "Secret operator", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "permissions": [{ "action": "operate", "resourceKind": "secret" }] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "permissions": { "items": { "additionalProperties": false, "properties": { "action": { "anyOf": [ { "const": "create", "type": "string" }, { "const": "read", "type": "string" }, { "const": "update", "type": "string" }, { "const": "delete", "type": "string" }, { "const": "deploy", "type": "string" }, { "const": "operate", "type": "string" }, { "const": "administer", "type": "string" }, { "const": "read_logs", "type": "string" }, { "const": "manage_policy", "type": "string" } ] }, "resourceKind": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "namespace", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "service_account", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" } ] } }, "required": ["action", "resourceKind"], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array" } }, "required": ["id", "namespaceId", "permissions"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create an immutable Namespace IAM Role", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/iam/roles/{roleId}": { "delete": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "deleteIAMRole", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "role-secret-operator" } }, "in": "path", "name": "roleId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete an unreferenced exact Namespace IAM Role", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] }, "get": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "getIAMRole", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "role-secret-operator" } }, "in": "path", "name": "roleId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "role-secret-operator", "name": "Secret operator", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "permissions": [{ "action": "operate", "resourceKind": "secret" }] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "permissions": { "items": { "additionalProperties": false, "properties": { "action": { "anyOf": [ { "const": "create", "type": "string" }, { "const": "read", "type": "string" }, { "const": "update", "type": "string" }, { "const": "delete", "type": "string" }, { "const": "deploy", "type": "string" }, { "const": "operate", "type": "string" }, { "const": "administer", "type": "string" }, { "const": "read_logs", "type": "string" }, { "const": "manage_policy", "type": "string" } ] }, "resourceKind": { "anyOf": [ { "const": "installation", "type": "string" }, { "const": "namespace", "type": "string" }, { "const": "configuration", "type": "string" }, { "const": "preset", "type": "string" }, { "const": "service_account", "type": "string" }, { "const": "secret", "type": "string" }, { "const": "agent", "type": "string" }, { "const": "agent_revision", "type": "string" }, { "const": "credential_source", "type": "string" }, { "const": "sandbox_policy", "type": "string" } ] } }, "required": ["action", "resourceKind"], "type": "object" }, "maxItems": 64, "minItems": 1, "type": "array" } }, "required": ["id", "namespaceId", "permissions"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an exact Namespace IAM Role", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/iam/service-principals": { "get": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "listIAMServicePrincipals", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "id": "principal-docs-agent", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "description": "A non-Agent automation identity fixed to one Namespace. It holds only the grants of AccessBindings that name it.", "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List the Namespace's non-Agent ServicePrincipals", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] }, "post": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "createIAMServicePrincipal", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "principal-docs-agent", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "A non-Agent automation identity fixed to one Namespace. It holds only the grants of AccessBindings that name it.", "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create a Namespace ServicePrincipal with no grants for automation or CLI keys", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/iam/service-principals/{servicePrincipalId}": { "get": { "description": "Requires administer permission on the requested Installation. Requires read permission on the requested Namespace.", "operationId": "getIAMServicePrincipal", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "principal-docs-agent" } }, "in": "path", "name": "servicePrincipalId", "required": true, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "principal-docs-agent", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "description": "A non-Agent automation identity fixed to one Namespace. It holds only the grants of AccessBindings that name it.", "properties": { "id": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an exact Namespace ServicePrincipal", "tags": ["IAM"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" }, { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/permissions": { "get": { "description": "Requires read permission on the requested Namespace.", "operationId": "getNamespaceCallerPermissions", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agents": { "create": true }, "delete": true, "installation": { "administer": true }, "secrets": { "create": true } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "agents": { "additionalProperties": false, "properties": { "create": { "description": "Whether the selected IAM Driver allows Agent creation in this Namespace now. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" } }, "required": ["create"], "type": "object" }, "delete": { "description": "Whether the selected IAM Driver allows deletion of this exact Namespace now. Advisory only: remaining resources, required Preset deletion permissions, or a later authorization decision can still prevent deletion.", "type": "boolean" }, "installation": { "additionalProperties": false, "properties": { "administer": { "description": "Whether the selected IAM Driver allows Installation administer now, which Installation-wide operations such as listing Backends need. The check targets the Installation, not this Namespace. Advisory only: a later authorization decision can still prevent the operation.", "type": "boolean" } }, "required": ["administer"], "type": "object" }, "secrets": { "additionalProperties": false, "properties": { "create": { "description": "Whether the selected IAM Driver allows Secret creation in this Namespace now. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "type": "boolean" } }, "required": ["create"], "type": "object" } }, "required": ["delete", "agents", "secrets", "installation"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Report advisory primary IAM permissions on a readable Namespace, not authorization for a later operation", "tags": ["Namespaces"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/permissions/secrets": { "get": { "description": "Requires read permission on the requested Namespace.", "operationId": "getNamespaceSecretPermissions", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "operateDenied": [] }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "operateDenied": { "description": "The IDs of the Namespace's Secrets that the caller may read but the selected IAM Driver does not allow Secret operate on now, sorted. Agent creation needs Secret operate on each Secret it binds or uses: its Harness authentication source, its Configuration's Secret bindings, and a directory search Secret. Empty when it is not reported: reported only to a caller who may create an Agent in this Namespace. Advisory only: other required permissions, lifecycle state, or a later authorization decision can still prevent the operation.", "items": { "minLength": 1, "type": "string" }, "type": "array" } }, "required": ["operateDenied"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Report the readable Secrets that the caller may not bind to a new Agent, not authorization for a later operation", "tags": ["Namespaces"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/presets": { "get": { "description": "Requires read permission on the requested Namespace. Only Preset resources with individual read permission are returned.", "operationId": "listPresets", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "createdAt": "2026-10-01T12:00:00.000Z", "id": "pre_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "description": "Preset summary without its template. Read the exact Preset for the template.", "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "id": { "pattern": "^pre_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId", "name", "createdAt"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List readable Preset summaries in one Namespace", "tags": ["Presets"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" }, { "action": "read", "resourceKind": "preset", "scope": "each_returned" } ] }, "post": { "description": "Requires create permission for Preset resources in the requested Namespace.", "operationId": "createPreset", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "name": "Documentation assistant", "template": { "agent": { "executionMode": "dedicated" }, "configuration": { "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } } } } } }, "schema": { "additionalProperties": false, "properties": { "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "template": { "additionalProperties": false, "description": "Reusable partial Agent launch settings. Scalar values may use {{ vars.name }}. Admission validates template syntax and credential boundaries. Ordinary creation APIs validate concrete launch settings.", "properties": { "agent": { "additionalProperties": false, "properties": { "backendId": { "$ref": "#/components/schemas/def-0" }, "executionMode": { "$ref": "#/components/schemas/def-0" }, "harnessAuth": { "$ref": "#/components/schemas/def-0" }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "$ref": "#/components/schemas/def-0" }, "pluginApprovers": { "$ref": "#/components/schemas/def-0" }, "plugins": { "$ref": "#/components/schemas/def-0" }, "repositoryAccess": { "$ref": "#/components/schemas/def-0" }, "repositoryBindings": { "$ref": "#/components/schemas/def-0" } }, "type": "object" }, "configuration": { "additionalProperties": false, "properties": { "secretBindings": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "Namespace-owned Secret bindings. Reference fields may use {{ vars.name }}.", "properties": {}, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "type": "object" }, "variables": { "additionalProperties": { "additionalProperties": false, "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "A value of the declared type. Password variables take no default." }, "description": { "type": "string" }, "type": { "anyOf": [ { "const": "string", "type": "string" }, { "const": "number", "type": "string" }, { "const": "boolean", "type": "string" }, { "const": "password", "type": "string" } ] } }, "required": ["type"], "type": "object" }, "type": "object" } }, "type": "object" } }, "required": ["name", "template"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "pre_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "template": { "agent": { "executionMode": "dedicated" }, "configuration": { "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } } } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "id": { "pattern": "^pre_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "template": { "additionalProperties": false, "description": "Reusable partial Agent launch settings. Scalar values may use {{ vars.name }}. Admission validates template syntax and credential boundaries. Ordinary creation APIs validate concrete launch settings.", "properties": { "agent": { "additionalProperties": false, "properties": { "backendId": { "$ref": "#/components/schemas/def-0" }, "executionMode": { "$ref": "#/components/schemas/def-0" }, "harnessAuth": { "$ref": "#/components/schemas/def-0" }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "$ref": "#/components/schemas/def-0" }, "pluginApprovers": { "$ref": "#/components/schemas/def-0" }, "plugins": { "$ref": "#/components/schemas/def-0" }, "repositoryAccess": { "$ref": "#/components/schemas/def-0" }, "repositoryBindings": { "$ref": "#/components/schemas/def-0" } }, "type": "object" }, "configuration": { "additionalProperties": false, "properties": { "secretBindings": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "Namespace-owned Secret bindings. Reference fields may use {{ vars.name }}.", "properties": {}, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "type": "object" }, "variables": { "additionalProperties": { "additionalProperties": false, "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "A value of the declared type. Password variables take no default." }, "description": { "type": "string" }, "type": { "anyOf": [ { "const": "string", "type": "string" }, { "const": "number", "type": "string" }, { "const": "boolean", "type": "string" }, { "const": "password", "type": "string" } ] } }, "required": ["type"], "type": "object" }, "type": "object" } }, "type": "object" } }, "required": ["id", "namespaceId", "name", "template", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create a reusable Namespace-owned Agent Preset", "tags": ["Presets"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "preset", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/presets/{presetId}": { "delete": { "description": "Requires delete permission on the requested Preset.", "operationId": "deletePreset", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "pre_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "presetId", "required": true, "schema": { "pattern": "^pre_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete a Preset without changing existing Agents", "tags": ["Presets"], "x-openclaw-permissions": [ { "action": "delete", "resourceKind": "preset", "scope": "requested" } ] }, "get": { "description": "Requires read permission on the requested Preset.", "operationId": "getPreset", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "pre_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "presetId", "required": true, "schema": { "pattern": "^pre_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "pre_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "template": { "agent": { "executionMode": "dedicated" }, "configuration": { "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } } } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "id": { "pattern": "^pre_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "template": { "additionalProperties": false, "description": "Reusable partial Agent launch settings. Scalar values may use {{ vars.name }}. Admission validates template syntax and credential boundaries. Ordinary creation APIs validate concrete launch settings.", "properties": { "agent": { "additionalProperties": false, "properties": { "backendId": { "$ref": "#/components/schemas/def-0" }, "executionMode": { "$ref": "#/components/schemas/def-0" }, "harnessAuth": { "$ref": "#/components/schemas/def-0" }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "$ref": "#/components/schemas/def-0" }, "pluginApprovers": { "$ref": "#/components/schemas/def-0" }, "plugins": { "$ref": "#/components/schemas/def-0" }, "repositoryAccess": { "$ref": "#/components/schemas/def-0" }, "repositoryBindings": { "$ref": "#/components/schemas/def-0" } }, "type": "object" }, "configuration": { "additionalProperties": false, "properties": { "secretBindings": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "Namespace-owned Secret bindings. Reference fields may use {{ vars.name }}.", "properties": {}, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "type": "object" }, "variables": { "additionalProperties": { "additionalProperties": false, "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "A value of the declared type. Password variables take no default." }, "description": { "type": "string" }, "type": { "anyOf": [ { "const": "string", "type": "string" }, { "const": "number", "type": "string" }, { "const": "boolean", "type": "string" }, { "const": "password", "type": "string" } ] } }, "required": ["type"], "type": "object" }, "type": "object" } }, "type": "object" } }, "required": ["id", "namespaceId", "name", "template", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Read one exact Namespace-owned Preset", "tags": ["Presets"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "preset", "scope": "requested" } ] }, "patch": { "description": "Requires update permission on the requested Preset.", "operationId": "updatePreset", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "pre_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "presetId", "required": true, "schema": { "pattern": "^pre_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "name": "Updated documentation assistant", "template": { "agent": { "executionMode": "dedicated" }, "configuration": { "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } } } } } }, "schema": { "additionalProperties": false, "minProperties": 1, "properties": { "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "template": { "additionalProperties": false, "description": "Reusable partial Agent launch settings. Scalar values may use {{ vars.name }}. Admission validates template syntax and credential boundaries. Ordinary creation APIs validate concrete launch settings.", "properties": { "agent": { "additionalProperties": false, "properties": { "backendId": { "$ref": "#/components/schemas/def-0" }, "executionMode": { "$ref": "#/components/schemas/def-0" }, "harnessAuth": { "$ref": "#/components/schemas/def-0" }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "$ref": "#/components/schemas/def-0" }, "pluginApprovers": { "$ref": "#/components/schemas/def-0" }, "plugins": { "$ref": "#/components/schemas/def-0" }, "repositoryAccess": { "$ref": "#/components/schemas/def-0" }, "repositoryBindings": { "$ref": "#/components/schemas/def-0" } }, "type": "object" }, "configuration": { "additionalProperties": false, "properties": { "secretBindings": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "Namespace-owned Secret bindings. Reference fields may use {{ vars.name }}.", "properties": {}, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "type": "object" }, "variables": { "additionalProperties": { "additionalProperties": false, "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "A value of the declared type. Password variables take no default." }, "description": { "type": "string" }, "type": { "anyOf": [ { "const": "string", "type": "string" }, { "const": "number", "type": "string" }, { "const": "boolean", "type": "string" }, { "const": "password", "type": "string" } ] } }, "required": ["type"], "type": "object" }, "type": "object" } }, "type": "object" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "createdAt": "2026-10-01T12:00:00.000Z", "id": "pre_123e4567-e89b-42d3-a456-426614174000", "name": "Documentation assistant", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "template": { "agent": { "executionMode": "dedicated" }, "configuration": { "values": { "agents": { "defaults": { "model": "codex/gpt-5.1-codex", "models": { "codex/gpt-5.1-codex": { "agentRuntime": { "id": "codex" } } } } }, "gateway": { "auth": { "password": { "id": "OPENCLAW_GATEWAY_PASSWORD", "provider": "default", "source": "env" } }, "bind": "lan", "controlUi": { "enabled": false }, "http": { "endpoints": { "chatCompletions": { "enabled": true } } }, "mode": "local" }, "models": { "providers": { "codex": { "api": "openai-responses", "baseUrl": "http://127.0.0.1:9", "models": [{ "id": "gpt-5.1-codex", "name": "gpt-5.1-codex" }] } } }, "plugins": { "allow": ["codex"], "entries": { "codex": { "config": { "appServer": { "approvalPolicy": "on-request", "authToken": "${APP_SERVER_TOKEN}", "mode": "guardian", "sandbox": "read-only", "transport": "websocket", "url": "${APP_SERVER_URL}" } }, "enabled": true } } } } } } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "createdAt": { "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[.][0-9]{3}Z$", "type": "string" }, "id": { "pattern": "^pre_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "template": { "additionalProperties": false, "description": "Reusable partial Agent launch settings. Scalar values may use {{ vars.name }}. Admission validates template syntax and credential boundaries. Ordinary creation APIs validate concrete launch settings.", "properties": { "agent": { "additionalProperties": false, "properties": { "backendId": { "$ref": "#/components/schemas/def-0" }, "executionMode": { "$ref": "#/components/schemas/def-0" }, "harnessAuth": { "$ref": "#/components/schemas/def-0" }, "initialWorkspaceFiles": { "additionalProperties": false, "properties": { "AGENTS.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "IDENTITY.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "SOUL.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" }, "USER.md": { "maxLength": 16384, "pattern": "^[^\\u0000]*$", "type": "string" } }, "type": "object" }, "name": { "$ref": "#/components/schemas/def-0" }, "pluginApprovers": { "$ref": "#/components/schemas/def-0" }, "plugins": { "$ref": "#/components/schemas/def-0" }, "repositoryAccess": { "$ref": "#/components/schemas/def-0" }, "repositoryBindings": { "$ref": "#/components/schemas/def-0" } }, "type": "object" }, "configuration": { "additionalProperties": false, "properties": { "secretBindings": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "Namespace-owned Secret bindings. Reference fields may use {{ vars.name }}.", "properties": {}, "type": "object" }, "values": { "additionalProperties": { "$ref": "#/components/schemas/def-0" }, "description": "A native OpenClaw configuration document.", "properties": {}, "type": "object" } }, "type": "object" }, "variables": { "additionalProperties": { "additionalProperties": false, "properties": { "default": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ], "description": "A value of the declared type. Password variables take no default." }, "description": { "type": "string" }, "type": { "anyOf": [ { "const": "string", "type": "string" }, { "const": "number", "type": "string" }, { "const": "boolean", "type": "string" }, { "const": "password", "type": "string" } ] } }, "required": ["type"], "type": "object" }, "type": "object" } }, "type": "object" } }, "required": ["id", "namespaceId", "name", "template", "createdAt"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Update a Preset without changing existing Agents", "tags": ["Presets"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "preset", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/secrets": { "get": { "description": "Requires read permission on the requested Namespace. Only Secret resources with individual read permission are returned.", "operationId": "listSecrets", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "name": "model-api-key", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ref": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "ref": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": ["id", "namespaceId", "name", "ref"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List readable Namespace-owned Secret metadata without revealing material", "tags": ["Secrets"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" }, { "action": "read", "resourceKind": "secret", "scope": "each_returned" } ] }, "post": { "description": "Requires create permission for Secret resources in the requested Namespace.", "operationId": "createSecret", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "name": "model-api-key", "value": "replace-with-your-authorized-model-key" } } }, "schema": { "additionalProperties": false, "properties": { "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "value": { "description": "Protected Secret value. It must be nonempty UTF-8 without NUL; OCC accepts at most 65,536 UTF-8 bytes and still enforces the route request body limit.", "maxLength": 65536, "minLength": 1, "pattern": "^[^\\u0000]*$", "type": "string" } }, "required": ["name", "value"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "name": "model-api-key", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ref": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "$ref": "#/components/schemas/def-12" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create exact Namespace-owned Secret material and return metadata only", "tags": ["Secrets"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "secret", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/secrets/{secretId}": { "delete": { "description": "Requires delete permission on the requested Secret.", "operationId": "deleteSecret", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sec_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "secretId", "required": true, "schema": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete exact unbound Namespace-owned Secret material", "tags": ["Secrets"], "x-openclaw-permissions": [ { "action": "delete", "resourceKind": "secret", "scope": "requested" } ] }, "get": { "description": "Requires read permission on the requested Secret.", "operationId": "getSecret", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sec_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "secretId", "required": true, "schema": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "callerPermissions": { "delete": true, "update": true }, "consumers": { "agents": ["agt_123e4567-e89b-42d3-a456-426614174000"], "configurations": [], "credentialSources": [], "provisioningRequests": [], "truncated": false, "unreadable": 0 }, "id": "sec_123e4567-e89b-42d3-a456-426614174000", "name": "model-api-key", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ref": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "callerPermissions": { "additionalProperties": false, "description": "What the selected IAM Driver allows you to do to this Secret now. Checking it records no authorization denial. Returned by the exact Secret read only.", "properties": { "delete": { "description": "Whether the selected IAM Driver allows you to delete this Secret now (Secret delete). Advisory only: current references, lifecycle state or a later authorization decision can still prevent the operation.", "type": "boolean" }, "update": { "description": "Whether the selected IAM Driver allows you to replace this Secret's value now (Secret update). Advisory only: lifecycle state or a later authorization decision can still prevent the operation.", "type": "boolean" } }, "required": ["update", "delete"], "type": "object" }, "consumers": { "additionalProperties": false, "description": "Current references that block deletion of the Secret. Returned by the exact Secret read only.", "properties": { "agents": { "description": "Agents that you can read. Each Agent has a Secret reference in its saved settings, selected Agent revision, or pending deployment. Deploy each Agent again to use a rotated value.", "items": { "pattern": "^agt_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "maxItems": 50, "type": "array" }, "configurations": { "description": "Readable Configurations whose `secretBindings` reference the Secret.", "items": { "pattern": "^cfg_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "maxItems": 50, "type": "array" }, "credentialSources": { "description": "Readable credential sources that hold the Secret.", "items": { "pattern": "^cs_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "maxItems": 50, "type": "array" }, "provisioningRequests": { "description": "Work IDs of queued or running Agent provisioning requests that reference the Secret, listed only for the actor that started them.", "items": { "maxLength": 200, "minLength": 1, "pattern": "^[A-Za-z0-9._~:@/-]{1,200}$", "type": "string" }, "maxItems": 50, "type": "array" }, "truncated": { "description": "`true` when the Secret has more than 50 references; only the first 50, ordered by kind and ID, are examined.", "type": "boolean" }, "unreadable": { "description": "Examined references to resources the caller may not read. They are counted, never named.", "maximum": 50, "minimum": 0, "type": "integer" } }, "required": [ "agents", "configurations", "credentialSources", "provisioningRequests", "unreadable", "truncated" ], "type": "object" }, "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "ref": { "additionalProperties": false, "description": "Exact OCC Secret reference. Shape: `{ \"kind\": \"secret\", \"namespaceId\": \"ns_...\", \"id\": \"sec_...\" }`.", "properties": { "id": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "kind": { "const": "secret", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["kind", "namespaceId", "id"], "type": "object" } }, "required": [ "id", "namespaceId", "name", "ref", "consumers", "callerPermissions" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get exact Namespace-owned Secret metadata and its readable consumers", "tags": ["Secrets"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "secret", "scope": "requested" } ] }, "patch": { "description": "Requires update permission on the requested Secret.", "operationId": "updateSecret", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sec_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "secretId", "required": true, "schema": { "pattern": "^sec_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "value": "replace-with-your-rotated-model-key" } } }, "schema": { "additionalProperties": false, "properties": { "value": { "description": "Protected Secret value. It must be nonempty UTF-8 without NUL; OCC accepts at most 65,536 UTF-8 bytes and still enforces the route request body limit.", "maxLength": 65536, "minLength": 1, "pattern": "^[^\\u0000]*$", "type": "string" } }, "required": ["value"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "name": "model-api-key", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "ref": { "id": "sec_123e4567-e89b-42d3-a456-426614174000", "kind": "secret", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "$ref": "#/components/schemas/def-12" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Replace exact Namespace-owned Secret material and return stable metadata", "tags": ["Secrets"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "secret", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/service-accounts": { "get": { "description": "Requires read permission on the requested Namespace. Only ServiceAccount resources with individual read permission are returned.", "operationId": "listServiceAccounts", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "id": "sa_123e4567-e89b-42d3-a456-426614174000", "name": "Model service account", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "credential": { "additionalProperties": false, "properties": { "kind": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "access_token", "type": "string" }, { "const": "oauth_access_token", "type": "string" } ] } }, "required": ["kind"], "type": "object" }, "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId", "name"], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List authorized Namespace-owned ServiceAccounts in one exact Namespace", "tags": ["Service accounts"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "namespace", "scope": "requested" }, { "action": "read", "resourceKind": "service_account", "scope": "each_returned" } ] }, "post": { "description": "Requires create permission for ServiceAccount resources in the requested Namespace.", "operationId": "createServiceAccount", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "name": "Model service account" } } }, "schema": { "additionalProperties": false, "properties": { "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" } }, "required": ["name"], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "sa_123e4567-e89b-42d3-a456-426614174000", "name": "Model service account", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "credential": { "additionalProperties": false, "properties": { "kind": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "access_token", "type": "string" }, { "const": "oauth_access_token", "type": "string" } ] } }, "required": ["kind"], "type": "object" }, "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId", "name"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Create a native Namespace-owned ServiceAccount", "tags": ["Service accounts"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "service_account", "scope": "namespace" } ] } }, "/namespaces/{namespaceId}/service-accounts/{serviceAccountId}": { "delete": { "description": "Requires delete permission on the requested ServiceAccount.", "operationId": "deleteServiceAccount", "parameters": [ { "description": "`true` deletes an account whose issued access token no ChatGPT Backend can revoke, and leaves the token for a ChatGPT workspace administrator to revoke at the provider. With a ChatGPT Backend configured it is ignored and the token is revoked as usual.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "false" } }, "in": "query", "name": "force", "required": false, "schema": { "anyOf": [ { "const": "true", "type": "string" }, { "const": "false", "type": "string" } ] } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sa_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "serviceAccountId", "required": true, "schema": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "sa_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000", "revocation": "skipped" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "description": "A forced deletion removed the account and its credential Secret but could not revoke its issued access token.", "properties": { "data": { "additionalProperties": false, "properties": { "backendId": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revocation": { "const": "skipped", "description": "The account's issued access token was not revoked: no ChatGPT Backend can revoke it. Revoke it at the provider; the audit event names its Backend and credential ID.", "type": "string" } }, "required": ["id", "namespaceId", "revocation"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "A forced deletion removed the account and its credential Secret but could not revoke its issued access token." }, "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete an exact unreferenced Namespace-owned ServiceAccount", "tags": ["Service accounts"], "x-openclaw-permissions": [ { "action": "delete", "resourceKind": "service_account", "scope": "requested" } ] }, "get": { "description": "Requires read permission on the requested ServiceAccount.", "operationId": "getServiceAccount", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sa_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "serviceAccountId", "required": true, "schema": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "id": "sa_123e4567-e89b-42d3-a456-426614174000", "name": "Model service account", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "credential": { "additionalProperties": false, "properties": { "kind": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "access_token", "type": "string" }, { "const": "oauth_access_token", "type": "string" } ] } }, "required": ["kind"], "type": "object" }, "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId", "name"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get an exact Namespace-owned ServiceAccount", "tags": ["Service accounts"], "x-openclaw-permissions": [ { "action": "read", "resourceKind": "service_account", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/service-accounts/{serviceAccountId}/credential": { "patch": { "description": "Requires update permission on the requested ServiceAccount.", "operationId": "updateServiceAccountCredential", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sa_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "serviceAccountId", "required": true, "schema": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "kind": "api_key", "secretRef": { "key": "value", "name": "model-api-key" } } } }, "schema": { "additionalProperties": false, "properties": { "kind": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "oauth_access_token", "type": "string" } ] }, "secretRef": { "additionalProperties": false, "properties": { "key": { "maxLength": 253, "pattern": "^(?![.]{1,2}$)[-._a-zA-Z0-9]+$", "type": "string" }, "name": { "maxLength": 253, "pattern": "^[a-z0-9](?:[-a-z0-9]*[a-z0-9])?(?:[.][a-z0-9](?:[-a-z0-9]*[a-z0-9])?)*$", "type": "string" } }, "required": ["name", "key"], "type": "object" } }, "required": ["kind", "secretRef"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "credential": { "kind": "api_key" }, "id": "sa_123e4567-e89b-42d3-a456-426614174000", "name": "Model service account", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "credential": { "additionalProperties": false, "properties": { "kind": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "access_token", "type": "string" }, { "const": "oauth_access_token", "type": "string" } ] } }, "required": ["kind"], "type": "object" }, "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId", "name"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Associate an exact Namespace-local credential reference with a ServiceAccount", "tags": ["Service accounts"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "service_account", "scope": "requested" } ] } }, "/namespaces/{namespaceId}/service-accounts/{serviceAccountId}/credentials": { "post": { "description": "Requires update permission on the requested ServiceAccount.", "operationId": "createServiceAccountCredential", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ns_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "namespaceId", "required": true, "schema": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "sa_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "serviceAccountId", "required": true, "schema": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": {} } }, "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "credential": { "kind": "access_token" }, "id": "sa_123e4567-e89b-42d3-a456-426614174000", "name": "Model service account", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "credential": { "additionalProperties": false, "properties": { "kind": { "anyOf": [ { "const": "api_key", "type": "string" }, { "const": "access_token", "type": "string" }, { "const": "oauth_access_token", "type": "string" } ] } }, "required": ["kind"], "type": "object" }, "id": { "pattern": "^sa_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "name": { "maxLength": 200, "minLength": 1, "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]+$", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["id", "namespaceId", "name"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Issue a managed credential for an exact Namespace-owned ServiceAccount", "tags": ["Service accounts"], "x-openclaw-permissions": [ { "action": "update", "resourceKind": "service_account", "scope": "requested" } ] } }, "/native-admin/return/{agentKey}": { "get": { "description": "Requires a human session with operate or administer permission on the exact Agent. Operate grants chat access; administer grants full native administration. Unknown and inaccessible Agents both return 404. This lookup does not launch or start the Agent.", "operationId": "resolveAgentNativeAdminReturn", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "123e4567e89b42d3a456426614174000" } }, "in": "path", "name": "agentKey", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "agentId": "agt_123e4567-e89b-42d3-a456-426614174000", "namespaceId": "ns_123e4567-e89b-42d3-a456-426614174000" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "description": "OK", "properties": { "data": { "additionalProperties": false, "properties": { "agentId": { "maxLength": 200, "minLength": 1, "type": "string" }, "namespaceId": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["namespaceId", "agentId"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Invalid Agent key" }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Not Found" }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NATIVE_ADMIN_RETURN_RATE_LIMITED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Too many requests; wait for Retry-After" }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "Service Unavailable" } }, "security": [{ "sessionCookie": [] }], "summary": "Resolve an authorized Agent from a copied native chat link", "tags": ["Agents"], "x-openclaw-permissions": [ { "action": "operate", "condition": "native_chat", "resourceKind": "agent", "scope": "requested" }, { "action": "administer", "condition": "native_admin_alternative", "resourceKind": "agent", "scope": "requested" } ] } }, "/oauth-clients": { "get": { "description": "Requires administer permission on the requested Installation.", "operationId": "listOAuthClients", "responses": { "200": { "content": { "application/json": { "examples": { "empty": { "summary": "No readable resources", "value": { "data": [], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } }, "example": { "summary": "Example response", "value": { "data": [ { "clientId": "example-client", "createdAt": "2026-10-01T12:00:00.000Z", "displayName": "Example provider client", "id": "ccr_123e4567-e89b-42d3-a456-426614174000", "issuer": "https://accounts.example.com", "tokenEndpointAuthMethod": "client_secret_basic", "tokenUrl": "https://accounts.example.com/token" } ], "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "items": { "additionalProperties": false, "properties": { "clientId": { "maxLength": 256, "minLength": 1, "type": "string" }, "createdAt": { "type": "string" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "id": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "tokenEndpointAuthMethod": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "client_secret_basic", "type": "string" }, { "const": "client_secret_post", "type": "string" } ] }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": [ "displayName", "clientId", "tokenEndpointAuthMethod", "issuer", "tokenUrl", "id", "createdAt" ], "type": "object" }, "type": "array" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "List registered OAuth clients", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] }, "post": { "description": "Requires administer permission on the requested Installation.", "operationId": "createOAuthClient", "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "clientId": "example-client", "clientSecret": "example-client-secret", "connectionTemplateId": "ctp_123e4567-e89b-42d3-a456-426614174000", "connectionTemplateVersion": 1, "displayName": "Example provider client", "tokenEndpointAuthMethod": "client_secret_basic" } } }, "schema": { "additionalProperties": false, "properties": { "clientId": { "maxLength": 256, "minLength": 1, "type": "string" }, "clientSecret": { "maxLength": 4096, "minLength": 1, "type": "string", "writeOnly": true }, "connectionTemplateId": { "pattern": "^ctp_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "connectionTemplateVersion": { "minimum": 1, "type": "integer" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "tokenEndpointAuthMethod": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "client_secret_basic", "type": "string" }, { "const": "client_secret_post", "type": "string" } ] } }, "required": [ "displayName", "clientId", "tokenEndpointAuthMethod", "connectionTemplateId", "connectionTemplateVersion" ], "type": "object" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "clientId": "example-client", "createdAt": "2026-10-01T12:00:00.000Z", "displayName": "Example provider client", "id": "ccr_123e4567-e89b-42d3-a456-426614174000", "issuer": "https://accounts.example.com", "tokenEndpointAuthMethod": "client_secret_basic", "tokenUrl": "https://accounts.example.com/token" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "clientId": { "maxLength": 256, "minLength": 1, "type": "string" }, "createdAt": { "type": "string" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "id": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "tokenEndpointAuthMethod": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "client_secret_basic", "type": "string" }, { "const": "client_secret_post", "type": "string" } ] }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": [ "displayName", "clientId", "tokenEndpointAuthMethod", "issuer", "tokenUrl", "id", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Register an OAuth client from a connection template", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/oauth-clients/{oauthClientId}": { "delete": { "description": "Requires administer permission on the requested Installation.", "operationId": "deleteOAuthClient", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ccr_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "oauthClientId", "required": true, "schema": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "responses": { "204": { "description": "No Content" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Delete an unused OAuth client", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/oauth-clients/{oauthClientId}/rotate-secret": { "post": { "description": "Requires administer permission on the requested Installation.", "operationId": "rotateOAuthClientSecret", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "ccr_123e4567-e89b-42d3-a456-426614174000" } }, "in": "path", "name": "oauthClientId", "required": true, "schema": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "example": { "summary": "Example request", "value": { "clientSecret": "replacement-example-client-secret" } } }, "schema": { "additionalProperties": false, "properties": { "clientSecret": { "maxLength": 4096, "minLength": 1, "type": "string", "writeOnly": true } }, "required": ["clientSecret"], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "clientId": "example-client", "createdAt": "2026-10-01T12:00:00.000Z", "displayName": "Example provider client", "id": "ccr_123e4567-e89b-42d3-a456-426614174000", "issuer": "https://accounts.example.com", "tokenEndpointAuthMethod": "client_secret_basic", "tokenUrl": "https://accounts.example.com/token" }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "clientId": { "maxLength": 256, "minLength": 1, "type": "string" }, "createdAt": { "type": "string" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "id": { "pattern": "^ccr_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "issuer": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "namespaceId": { "pattern": "^ns_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, "revocationUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" }, "tokenEndpointAuthMethod": { "anyOf": [ { "const": "none", "type": "string" }, { "const": "client_secret_basic", "type": "string" }, { "const": "client_secret_post", "type": "string" } ] }, "tokenUrl": { "maxLength": 2048, "pattern": "^https://[^\\s/]", "type": "string" } }, "required": [ "displayName", "clientId", "tokenEndpointAuthMethod", "issuer", "tokenUrl", "id", "createdAt" ], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "redirectUri": { "type": "string" }, "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "409": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RESOURCE_CONFLICT" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested operation conflicts with the current resource state." }, "413": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/PAYLOAD_TOO_LARGE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request body exceeds the permitted size." }, "415": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNSUPPORTED_MEDIA_TYPE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request content type is not supported." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Rotate an OAuth client secret", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } }, "/oauth/callback": { "get": { "description": "Requires the signed-in human session that started the connection, permission to create a credential source in the starting Namespace, and a template available there. The provider redirects here with `state` and `code`, or with `error`. The response is a 303 redirect to the console without the query string.", "operationId": "completeNamespaceConnection", "parameters": [ { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "example-browser-bound-state" } }, "in": "query", "name": "state", "required": false, "schema": { "maxLength": 512, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "example-provider-code" } }, "in": "query", "name": "code", "required": false, "schema": { "maxLength": 4096, "type": "string" } }, { "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "access_denied" } }, "in": "query", "name": "error", "required": false, "schema": { "maxLength": 256, "type": "string" } }, { "description": "Authorization server issuer. Must match the connection template when present. Required for code exchange if another issuer has a client registration when consent starts or when the callback arrives.", "examples": { "example": { "summary": "Example parameter; replace resource IDs with values from your Installation.", "value": "https://accounts.example.com" } }, "in": "query", "name": "iss", "required": false, "schema": { "maxLength": 2048, "type": "string" } } ], "responses": { "303": { "content": { "application/json": { "schema": { "description": "Redirect to the console with the connection outcome" } } }, "description": "Redirect to the console with the connection outcome" }, "429": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/RATE_LIMITED" } }, "schema": { "description": "Too many requests; wait for Retry-After" } } }, "description": "Too many requests; wait for Retry-After" } }, "security": [{ "sessionCookie": [] }], "summary": "Complete a browser connection for the signed-in person who started it", "tags": ["Connections"], "x-openclaw-permissions": [ { "action": "create", "resourceKind": "credential_source", "scope": "namespace" } ] } }, "/observability": { "get": { "description": "Requires administer permission on the requested Installation.", "operationId": "getObservability", "responses": { "200": { "content": { "application/json": { "examples": { "example": { "summary": "Example response", "value": { "data": { "url": null }, "meta": { "requestId": "req_123e4567-e89b-42d3-a456-426614174000" } } } }, "schema": { "additionalProperties": false, "properties": { "data": { "additionalProperties": false, "properties": { "url": { "anyOf": [{ "format": "uri", "type": "string" }, { "type": "null" }] } }, "required": ["url"], "type": "object" }, "meta": { "additionalProperties": false, "properties": { "requestId": { "pattern": "^req_[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" } }, "required": ["requestId"], "type": "object" } }, "required": ["data", "meta"], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INVALID_REQUEST" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The request does not match the operation contract." }, "401": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/UNAUTHENTICATED" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller did not provide valid credentials." }, "403": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/FORBIDDEN" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The caller is not allowed to perform this operation." }, "404": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/NOT_FOUND" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The requested platform resource was not found." }, "500": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/INTERNAL_ERROR" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "The platform request could not be completed." }, "503": { "content": { "application/json": { "examples": { "example": { "$ref": "#/components/examples/DEPENDENCY_UNAVAILABLE" } }, "schema": { "$ref": "#/components/schemas/def-7" } } }, "description": "A required dependency is unavailable." } }, "summary": "Get the configured external observability destination", "tags": ["Installation"], "x-openclaw-permissions": [ { "action": "administer", "resourceKind": "installation", "scope": "requested" } ] } } }, "security": [{ "sessionCookie": [] }, { "serviceApiKey": [] }], "servers": [{ "description": "Your OCC Installation origin", "url": "/" }] }