{ "openapi": "3.1.0", "info": { "title": "CapWorks OpenConnector API", "version": "1.0.0" }, "tags": [ { "name": "System", "description": "Runtime health and server-level status." }, { "name": "Catalog", "description": "Provider and action metadata used by users and agents." }, { "name": "Connections", "description": "Local provider credentials and connection state." }, { "name": "OAuth", "description": "Local OAuth client configuration and authorization flow." }, { "name": "Access", "description": "Runtime execution policy and bearer tokens for /v1 and MCP clients." }, { "name": "Files", "description": "Local temporary file transit for provider actions." }, { "name": "Runs", "description": "Local action execution and recent run history." }, { "name": "Proxy", "description": "Provider API proxy requests through local credentials." }, { "name": "MCP", "description": "Stateless MCP POST endpoint and tool metadata." } ], "paths": { "/health": { "get": { "tags": [ "System" ], "summary": "Unauthenticated process health check.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": false, "required": [ "ok" ], "description": "Process health payload." } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/health": { "get": { "tags": [ "System" ], "summary": "Runtime health check.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "runtime": { "type": "string", "description": "Runtime identifier." } }, "additionalProperties": false, "required": [ "ok", "runtime" ], "description": "Runtime health payload." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } } } } }, "/api/auth/session": { "get": { "tags": [ "System" ], "summary": "Read local admin auth session state.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalAuthSession" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/auth/logout": { "post": { "tags": [ "System" ], "summary": "Clear the local admin auth cookie.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "additionalProperties": false, "required": [ "ok" ], "description": "Local auth logout response." } } } } } } }, "/api/providers": { "get": { "tags": [ "Catalog" ], "summary": "List provider catalog entries.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderDefinition" } } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/providers/{service}": { "get": { "tags": [ "Catalog" ], "summary": "Get one provider catalog entry.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProviderDefinition" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/actions": { "get": { "tags": [ "Catalog" ], "summary": "List all catalog actions.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActionDefinition" } } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/actions/search": { "get": { "tags": [ "Catalog" ], "summary": "Fuzzy keyword search over the action catalog.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActionSearchResult" } } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/providers": { "get": { "tags": [ "Catalog" ], "summary": "List public provider catalog entries.", "description": "Closest HTTP analog of MCP list_apps. Categories are objects; MCP list_apps returns strings.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional case-insensitive filter over service, display name, scenario, category, or auth type." }, { "name": "service", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Optional provider service id. Repeat to include multiple providers." } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeProviderMetadata" } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } } } } }, "/v1/actions": { "get": { "tags": [ "Catalog" ], "summary": "List action services, or actions for one service.", "description": "Without service, data is [{service}]. With service, data is RuntimeActionMetadata.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Provider service id. Omit to list services instead of actions." } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeActionService" } }, { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeActionMetadata" } } ], "description": "Runtime action index payload." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } } } } }, "/v1/actions/search": { "get": { "tags": [ "Catalog" ], "summary": "Fuzzy keyword search over the action catalog.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search text. Provide either q or query." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alias for q. Provide either q or query." }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional provider service id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "description": "Maximum actions to return. Defaults to 10. Maximum 50." } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActionSearchResult" } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } } } } }, "/v1/apps": { "get": { "tags": [ "Connections" ], "summary": "List connected accounts.", "description": "RuntimeConnectedApp rows, not the provider catalog. Use GET /v1/providers or MCP list_apps for providers.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeConnectedApp" } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } } } } }, "/v1/apps/authenticated": { "get": { "tags": [ "Connections" ], "summary": "Return authenticated provider service IDs from the supplied candidates.", "parameters": [ { "name": "service", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Candidate service id to check. Repeat to check multiple services." } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "type": "array", "items": { "type": "string" }, "description": "Authenticated service IDs from the supplied candidates." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } } } } }, "/v1/apps/services/{service}": { "get": { "tags": [ "Connections" ], "summary": "List connected accounts for one provider.", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string", "description": "Provider service identifier." } } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeConnectedApp" } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } } } } }, "/api/actions/{actionId}": { "get": { "tags": [ "Catalog" ], "summary": "Get one catalog action.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionDefinition" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/actions/{actionId}/agent.md": { "get": { "tags": [ "Catalog" ], "summary": "Get one markdown action guide.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "string", "description": "Markdown guide for one action." } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/connections": { "get": { "tags": [ "Connections" ], "summary": "List local provider connections.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConnectionSummary" } } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/connections/{service}": { "put": { "tags": [ "Connections" ], "summary": "Create or replace a local provider connection.", "description": "The accepted auth type and credential field keys are declared by the provider catalog auth metadata. Unknown fields are rejected.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionUpsertRequest" } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionSummary" } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Connections" ], "summary": "Disconnect a provider.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ConnectionSummary" }, { "type": "object", "properties": { "service": { "type": "string" }, "configured": { "const": false, "type": "boolean" } }, "additionalProperties": false, "required": [ "service", "configured" ], "description": "Disconnected provider summary." } ] } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/oauth/configs": { "get": { "tags": [ "OAuth" ], "summary": "List local OAuth client configurations.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthClientConfigSummary" } } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/oauth/configs/{service}": { "put": { "tags": [ "OAuth" ], "summary": "Upsert local OAuth client configuration.", "description": "Open-source users provide their own OAuth app. requestedScopes may narrow the provider-declared defaults but cannot add scopes. Additional extra fields are declared by provider catalog auth metadata.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientConfigRequest" } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientConfigSummary" } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "OAuth" ], "summary": "Delete local OAuth client configuration.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string" }, "configured": { "const": false, "type": "boolean" } }, "additionalProperties": false, "required": [ "service", "configured" ], "description": "Deleted OAuth client config summary." } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/oauth/authorizations": { "post": { "tags": [ "OAuth" ], "summary": "Start provider OAuth authorization.", "description": "The console may provide a connection-scoped OAuth app through clientId/clientSecret and provider-declared extra fields. The provider must be enabled through OOMOL_CONNECT_ALLOWED_CUSTOM_OAUTH and pending OAuth state requires OOMOL_CONNECT_ENCRYPTION_KEY.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string", "description": "Provider service identifier." }, "connectionName": { "type": "string", "description": "Optional local connection name. Defaults to default." }, "clientId": { "type": "string", "description": "Optional connection-scoped OAuth app client id." }, "clientSecret": { "type": "string", "description": "Optional connection-scoped OAuth app client secret." }, "requestedScopes": { "type": "array", "items": { "type": "string" }, "description": "Optional non-empty provider-declared scope subset to request.", "minItems": 1 }, "extra": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-declared non-secret OAuth client fields." }, "secretExtra": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider-declared secret OAuth client fields." } }, "additionalProperties": false, "required": [ "service" ], "description": "OAuth authorization creation request." } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "service": { "type": "string" }, "authorizationUrl": { "type": "string" }, "state": { "type": "string" } }, "additionalProperties": false, "required": [ "service", "authorizationUrl", "state" ], "description": "OAuth authorization start response." } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/runtime-tokens": { "get": { "tags": [ "Access" ], "summary": "List runtime API token summaries.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RuntimeTokenSummary" } } } } } } }, "post": { "tags": [ "Access" ], "summary": "Create a runtime API token.", "description": "The plaintext token is returned once. Only a hash is stored locally. Policy request bodies must not exceed 262144 bytes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeTokenCreateRequest" } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Plaintext runtime bearer token. Store it now." }, "record": { "$ref": "#/components/schemas/RuntimeTokenSummary" } }, "additionalProperties": false, "required": [ "token", "record" ], "description": "Runtime token creation response." } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/runtime-tokens/{id}": { "put": { "tags": [ "Access" ], "summary": "Replace one stored runtime token's permissions.", "description": "Policy request bodies must not exceed 262144 bytes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenPolicy" } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimeTokenSummary" } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Access" ], "summary": "Revoke a runtime API token.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "revoked": { "type": "boolean" } }, "additionalProperties": false, "required": [ "id", "revoked" ], "description": "Runtime token revocation response." } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/runtime-policy": { "get": { "tags": [ "Access" ], "summary": "Read deployment and persisted Runtime policy layers.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimePolicyState" } } } }, "500": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Access" ], "summary": "Replace the persisted Runtime action and proxy policy.", "description": "Deployment policy remains read-only. Block rules take precedence and non-empty allowlists intersect. Policy request bodies must not exceed 262144 bytes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyRules" } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuntimePolicyState" } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/files": { "post": { "tags": [ "Files" ], "summary": "Upload one local transit file.", "description": "Stores one temporary local file and returns a download URL for connector actions.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "File content to upload." } }, "additionalProperties": false, "required": [ "file" ], "description": "Transit file upload request." } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitFileUpload" } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "413": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/files/{fileId}": { "get": { "tags": [ "Files" ], "summary": "Download one local transit file.", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "description": "Opaque local transit file identifier." } } ], "responses": { "200": { "description": "Transit file bytes.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Files" ], "summary": "Delete one local transit file.", "parameters": [ { "name": "fileId", "in": "path", "required": true, "schema": { "type": "string", "description": "Opaque local transit file identifier." } } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string" }, "deleted": { "type": "boolean" } }, "additionalProperties": false, "required": [ "fileId", "deleted" ], "description": "Transit file deletion response." } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/actions/{actionId}": { "get": { "tags": [ "Catalog" ], "summary": "Get one runtime action.", "parameters": [ { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string", "description": "Action id, usually .." } } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "$ref": "#/components/schemas/RuntimeActionMetadata" }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } }, "404": { "description": "unknown_action.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } } } }, "post": { "tags": [ "Runs" ], "summary": "Execute a runtime action.", "description": "Use the action catalog to discover provider-specific input and output schemas. For a compact strongly typed OpenAPI document for one action, request /openapi.json?actionId=. Requests with the same Idempotency-Key, action, input, effective connection, and stored runtime token identity replay the original HTTP status and body of completed successes and failures during the 24-hour replay window. Requests that are still in progress, or whose outcome is uncertain, are not automatically dispatched again. Duplicate suppression does not guarantee exactly-once execution by the provider.", "parameters": [ { "name": "actionId", "in": "path", "required": true, "schema": { "type": "string", "description": "Action id, usually .." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1 }, "description": "Optional runtime-wide key for deduplicating retries of the same action request. Leading and trailing whitespace is trimmed; the remaining value must be non-empty and must not exceed 255 UTF-8 bytes. Reuse a key only for retries with the same action, input, effective connection, and stored runtime token. When this header is present, the action input must not exceed an object/array nesting depth of 100 levels." }, { "name": "x-oo-connector-alias", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." }, { "name": "connectionName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." }, { "name": "alias", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": true, "description": "Action input matching the catalog schema. Omitted input is treated as {}." }, "connectionName": { "type": "string", "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." }, "alias": { "type": "string", "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." } }, "additionalProperties": false, "description": "Generic action run creation request." } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "description": "Action output matching the catalog schema." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Action execution identifier." }, "actionId": { "type": "string", "description": "Executed action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "executionId", "actionId", "auditPersisted" ], "description": "Action execution metadata." } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } }, "400": { "description": "invalid_input, action_blocked, or action_not_allowed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "402": { "description": "insufficient_credit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "403": { "description": "authorization_failed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "404": { "description": "unknown_action or connection_not_found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "409": { "description": "For idempotency, idempotency_request_in_progress means the original request is still running or its outcome is uncertain, while idempotency_key_conflict means the key was reused for a different action, input, effective connection, or stored runtime token. Other runtime conflicts may return their own error code with the same status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "413": { "description": "The provider response exceeded the runtime size limit, or the upstream answered 413.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "429": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "500": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "properties": { "executionId": { "type": "string", "description": "Execution identifier when action execution began." }, "actionId": { "type": "string", "description": "Requested action identifier." }, "auditPersisted": { "type": "boolean", "description": "Whether the run audit record was stored." } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Action failure metadata. Execution fields are omitted when execution did not begin." } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } } } } }, "/v1/proxy/{service}": { "post": { "tags": [ "Proxy" ], "summary": "Proxy one provider API request.", "description": "For providers with a local proxy executor, forwards a provider-relative HTTP request and applies stored provider credentials locally.", "parameters": [ { "name": "service", "in": "path", "required": true, "schema": { "type": "string", "description": "Provider service identifier." } }, { "name": "x-oo-connector-alias", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." }, { "name": "connectionName", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." }, { "name": "alias", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "description": "Provider-relative path beginning with /." }, "method": { "type": "string", "description": "HTTP method: DELETE, GET, HEAD, PATCH, POST, or PUT." }, "query": { "type": "object", "additionalProperties": true, "description": "Provider query parameters. Scalar values are forwarded." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider request headers. Hop-by-hop and auth headers are not forwarded." }, "body": { "description": "Provider request body." }, "connectionName": { "type": "string", "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." }, "alias": { "type": "string", "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." } }, "additionalProperties": false, "required": [ "endpoint", "method" ], "description": "Provider proxy request." } } } }, "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true, "type": "boolean" }, "message": { "const": "OK", "type": "string" }, "data": { "type": "object", "properties": { "status": { "type": "integer", "description": "Provider HTTP response status." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Provider response headers." }, "bodyEncoding": { "type": "string", "description": "Present as base64 when the provider response is binary." }, "data": { "description": "Provider response payload." } }, "additionalProperties": false, "required": [ "status", "headers", "data" ], "description": "Provider proxy response." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "meta" ], "description": "Runtime success envelope." } } } }, "400": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "402": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "403": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "409": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "413": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "429": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "500": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } }, "501": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false, "type": "boolean" }, "message": { "type": "string", "description": "Human-readable error message." }, "data": { "description": "Provider or validation error details." }, "errorCode": { "type": "string", "description": "Stable machine-readable error code." }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": false, "required": [ "success", "message", "data", "errorCode", "meta" ], "description": "Runtime failure envelope." } } } } } } }, "/api/runs": { "get": { "tags": [ "Runs" ], "summary": "List recent local action runs.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "description": "Maximum number of runs to return." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor returned by the previous page." }, { "name": "service", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only return runs whose action id belongs to this service." }, { "name": "actionId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 256 }, "description": "Only return runs for this exact action id." }, { "name": "caller", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "http", "mcp", "web" ] }, "description": "Only return runs from this runtime entry point." }, { "name": "ok", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only return successful or failed runs." } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunLogPage" } } } } } } }, "/api/runs/{id}": { "get": { "tags": [ "Runs" ], "summary": "Get one local action run.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Action execution identifier." } ], "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunLog" } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/mcp": { "post": { "tags": [ "MCP" ], "summary": "Handle stateless MCP JSON-RPC POST requests.", "responses": { "200": { "description": "MCP JSON-RPC response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "/mcp/tools": { "get": { "tags": [ "MCP" ], "summary": "List discovery-oriented MCP tool summaries.", "responses": { "200": { "description": "JSON response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "tools": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "tools" ] } } } }, "404": { "description": "JSON response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "ActionDefinition": { "type": "object", "additionalProperties": true, "description": "Public action catalog definition with runtime execution status." }, "LocalAuthSession": { "type": "object", "properties": { "adminAuthConfigured": { "type": "boolean", "description": "Whether the local admin API requires an admin bearer token." }, "authenticated": { "type": "boolean", "description": "Whether this request is authenticated for local admin APIs." } }, "additionalProperties": false, "required": [ "adminAuthConfigured", "authenticated" ], "description": "Local web console admin authentication state." }, "ActionSearchResult": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique action identifier." }, "service": { "type": "string", "description": "The provider service that owns the action." }, "name": { "type": "string", "description": "The provider-scoped action name." }, "description": { "type": "string", "description": "The action description." }, "authenticated": { "type": "boolean", "description": "Whether the provider service has an authenticated local connection." }, "inputSchema": { "type": "object", "additionalProperties": true, "description": "The normalized JSON Schema for the action input." }, "outputSchema": { "type": "object", "additionalProperties": true, "description": "The normalized JSON Schema for the action output." } }, "additionalProperties": false, "required": [ "id", "service", "name", "description", "authenticated", "inputSchema", "outputSchema" ], "description": "A single action returned by fuzzy keyword search." }, "RuntimeProviderMetadata": { "type": "object", "properties": { "service": { "type": "string", "description": "Provider service identifier." }, "displayName": { "type": "string", "description": "Human-readable provider name." }, "iconUrl": { "anyOf": [ { "type": "string", "description": "Provider icon URL." }, { "type": "null" } ] }, "homepageUrl": { "anyOf": [ { "type": "string", "description": "Provider homepage URL." }, { "type": "null" } ] }, "scenario": { "type": "string", "description": "Broad task-oriented provider discovery scenario." }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" } }, "additionalProperties": false, "required": [ "id", "displayName" ], "description": "Catalog category." } }, "authTypes": { "type": "array", "items": { "type": "string" }, "description": "Supported authentication types." } }, "additionalProperties": false, "required": [ "service", "displayName", "iconUrl", "homepageUrl", "scenario", "categories", "authTypes" ], "description": "Public provider catalog row from GET /v1/providers." }, "RuntimeActionService": { "type": "object", "properties": { "service": { "type": "string", "description": "Provider service identifier." } }, "additionalProperties": false, "required": [ "service" ], "description": "Service index row from GET /v1/actions when service is omitted." }, "RuntimeActionMetadata": { "type": "object", "properties": { "id": { "type": "string", "description": "Full action id, usually .." }, "service": { "type": "string", "description": "Provider service that owns the action." }, "name": { "type": "string", "description": "Provider-scoped action name." }, "description": { "type": "string", "description": "Action description." }, "requiredScopes": { "type": "array", "items": { "type": "string" } }, "providerPermissions": { "type": "array", "items": { "type": "string" } }, "inputSchema": { "type": "object", "additionalProperties": true, "description": "Normalized JSON Schema for the action input." }, "outputSchema": { "type": "object", "additionalProperties": true, "description": "Normalized JSON Schema for the action output." }, "followUpActions": { "type": "array", "items": { "type": "object", "properties": { "actionId": { "type": "string" } }, "additionalProperties": false, "required": [ "actionId" ], "description": "Follow-up action." } }, "asyncLifecycle": { "anyOf": [ { "type": "object", "additionalProperties": true, "description": "Start/status/cancel action ids." }, { "type": "null" } ] }, "execution": { "type": "object", "properties": { "locallyExecutable": { "type": "boolean" }, "catalogOnly": { "type": "boolean" }, "requiredAuthTypes": { "type": "array", "items": { "type": "string" } }, "noAuthRunnable": { "type": "boolean" }, "needsCredential": { "type": "boolean" } }, "additionalProperties": false, "required": [ "locallyExecutable", "catalogOnly", "requiredAuthTypes", "noAuthRunnable", "needsCredential" ], "description": "Runtime execution status." } }, "additionalProperties": false, "required": [ "id", "service", "name", "description", "requiredScopes", "providerPermissions", "inputSchema", "outputSchema", "followUpActions", "asyncLifecycle", "execution" ], "description": "Public runtime action metadata." }, "RuntimeConnectedApp": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable local connection identifier." }, "service": { "type": "string", "description": "Provider service identifier." }, "status": { "type": "string", "enum": [ "active", "disconnected" ] }, "alias": { "type": "string", "description": "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default." }, "authType": { "type": "string", "description": "Connection authentication type." }, "displayName": { "type": "string", "description": "Human-readable account label." }, "accountLabel": { "type": "string", "description": "Same value as displayName. Kept for existing /v1 clients." }, "isDefault": { "type": "boolean", "description": "Whether this is the default connection. Same fact as MCP default." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Granted scopes. Same fact as MCP profile.grantedScopes." } }, "additionalProperties": false, "required": [ "id", "service", "status", "alias", "authType", "displayName", "accountLabel", "isDefault", "scopes" ], "description": "Connected account from GET /v1/apps." }, "ConnectionSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable local connection identifier." }, "service": { "type": "string", "description": "Provider service identifier." }, "authType": { "type": "string", "description": "Connection authentication type." }, "configured": { "type": "boolean", "description": "Whether the provider is connected." }, "virtual": { "type": "boolean", "description": "Whether the connection needs no stored secret." }, "profile": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Provider-side account, user, workspace, bot, or token identifier." }, "displayName": { "type": "string", "description": "Human-readable account label shown to users and agents." }, "grantedScopes": { "type": "array", "items": { "type": "string" }, "description": "Provider-native scopes granted to the stored credential, when known." } }, "additionalProperties": false, "required": [ "accountId", "displayName", "grantedScopes" ], "description": "Stable provider account identity safe for users and agents." } }, "additionalProperties": false, "required": [ "id", "service", "authType", "configured", "virtual", "profile" ], "description": "Local provider connection summary." }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable error message." }, "details": {} }, "additionalProperties": false, "required": [ "code", "message" ], "description": "Error payload." } }, "additionalProperties": false, "required": [ "error" ], "description": "Standard error response." }, "ConnectionUpsertRequest": { "type": "object", "properties": { "authType": { "type": "string", "description": "Connection auth type: no_auth, api_key, or custom_credential." }, "connectionName": { "type": "string", "description": "Optional local connection name. Defaults to default." }, "values": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Credential values keyed by provider-declared field ids." } }, "additionalProperties": false, "required": [ "authType" ], "description": "Connection upsert request." }, "OAuthClientConfigSummary": { "type": "object", "properties": { "service": { "type": "string", "description": "Provider service identifier." }, "configured": { "type": "boolean", "description": "Whether a local OAuth client config is configured." }, "customClientAvailable": { "type": "boolean", "description": "Whether the console may use a connection-scoped OAuth client for this provider." }, "clientId": { "anyOf": [ { "type": "string", "description": "Configured OAuth client id." }, { "type": "null" } ] }, "expectedRedirectUri": { "type": "string", "description": "Callback URL to configure in the provider OAuth app." }, "auth": { "type": "object", "additionalProperties": true, "description": "Provider OAuth capability metadata." }, "requestedScopes": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "description": "Configured scope subset, or null when provider defaults are used." }, { "type": "null" } ] }, "effectiveScopes": { "type": "array", "items": { "type": "string" }, "description": "Scopes the runtime will include in new authorization requests." } }, "additionalProperties": false, "required": [ "service", "configured", "customClientAvailable", "clientId", "expectedRedirectUri", "auth", "requestedScopes", "effectiveScopes" ], "description": "OAuth client config summary safe for the local console." }, "OAuthClientConfigRequest": { "type": "object", "properties": { "clientId": { "type": "string", "description": "OAuth app client id." }, "clientSecret": { "type": "string", "description": "OAuth app client secret. Optional only for public-client providers." }, "requestedScopes": { "type": "array", "items": { "type": "string" }, "description": "Non-empty provider-declared scope subset to request. Omit to use every provider default.", "minItems": 1 }, "extra": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional OAuth client config values keyed by provider-declared field ids." }, "secretExtra": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Sensitive OAuth client config values keyed by provider-declared field ids." } }, "additionalProperties": false, "required": [ "clientId" ], "description": "User-provided OAuth app client configuration." }, "RuntimeTokenSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Runtime token identifier." }, "name": { "type": "string", "description": "User-facing token label." }, "allowedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Action allow rules applied to this stored runtime token." }, "blockedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Action block rules applied to this stored runtime token." }, "allowedProxies": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Provider proxies explicitly granted to this token. An empty list grants no proxy access." }, "allowedConnections": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque stable connection ID returned by a connection API." }, "description": "Stable connection IDs granted to this stored runtime token. An empty list is unrestricted connection access. IDs are opaque values returned by the connection APIs. Virtual no_auth connections do not require grants." }, "createdAt": { "type": "string", "description": "Creation timestamp." }, "lastUsedAt": { "type": "string", "description": "Last successful use timestamp." } }, "additionalProperties": false, "required": [ "id", "name", "allowedActions", "blockedActions", "allowedProxies", "allowedConnections", "createdAt" ], "description": "Runtime API token summary. Plaintext tokens and token hashes are not returned." }, "RuntimeTokenCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "User-facing token label." }, "allowedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Optional action allow rules for the new token." }, "blockedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Optional action block rules for the new token." }, "allowedProxies": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Optional provider proxy grants for the new token. Omit or leave empty to deny proxy access." }, "allowedConnections": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque stable connection ID returned by a connection API." }, "description": "Optional stable connection IDs granted to the new token. Omit or leave empty for unrestricted connection access. A non-empty list matches exact opaque IDs returned by the connection APIs. Virtual no_auth connections do not require grants." } }, "additionalProperties": false, "required": [ "name" ], "description": "Runtime token creation request." }, "TokenPolicy": { "type": "object", "properties": { "allowedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Action allow rules for this token." }, "blockedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Action block rules for this token." }, "allowedProxies": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Provider proxies explicitly granted to this token. An empty list grants no proxy access." }, "allowedConnections": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Opaque stable connection ID returned by a connection API." }, "description": "Stable connection IDs granted to this stored token. An empty list is unrestricted connection access. A non-empty list matches exact opaque IDs returned by the connection APIs. Virtual no_auth connections do not require grants." } }, "additionalProperties": false, "required": [ "allowedActions", "blockedActions", "allowedProxies", "allowedConnections" ], "description": "Complete replacement of one stored runtime token's action, proxy, and connection permissions." }, "PolicyRules": { "type": "object", "properties": { "allowedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Action allow rules." }, "blockedActions": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Action block rules." }, "allowedProxies": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Proxy service allow rules." }, "blockedProxies": { "type": "array", "maxItems": 128, "items": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy rule. The server enforces a 256-byte UTF-8 limit." }, "description": "Proxy service block rules." } }, "additionalProperties": false, "required": [ "allowedActions", "blockedActions", "allowedProxies", "blockedProxies" ], "description": "One complete action and proxy policy layer." }, "RuntimePolicyState": { "type": "object", "properties": { "deployment": { "$ref": "#/components/schemas/PolicyRules" }, "runtime": { "$ref": "#/components/schemas/PolicyRules" }, "updatedAt": { "type": "string", "description": "Last Runtime policy update timestamp, when configured." } }, "additionalProperties": false, "required": [ "deployment", "runtime" ], "description": "Deployment and persisted Runtime policy layers. Deployment rules are read-only." }, "PolicyCheck": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "deployment", "runtime", "token" ] }, "outcome": { "type": "string", "enum": [ "allow_match", "block_match", "allow_miss" ] }, "rule": { "type": "string", "description": "First matching policy rule, when one matched." } }, "additionalProperties": false, "required": [ "source", "outcome" ], "description": "One policy layer's decisive or matching check." }, "PolicyDecision": { "type": "object", "properties": { "allowed": { "type": "boolean", "description": "Whether policy permits execution." }, "code": { "type": "string", "enum": [ "action_not_allowed", "action_blocked", "proxy_not_allowed", "proxy_blocked", "connection_not_allowed" ] }, "message": { "type": "string", "description": "Policy denial message." }, "checks": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/PolicyCheck" } } }, "additionalProperties": false, "required": [ "allowed", "checks" ], "description": "Layered execution policy decision. code and message are present on denial." }, "TransitFileUpload": { "type": "object", "properties": { "fileId": { "type": "string", "description": "Opaque local transit file identifier." }, "downloadUrl": { "type": "string", "description": "URL that serves the uploaded file." }, "sizeBytes": { "type": "number", "description": "Uploaded file size in bytes." }, "name": { "type": "string", "description": "Original uploaded filename." }, "mimeType": { "type": "string", "description": "Uploaded file MIME type." } }, "additionalProperties": false, "required": [ "fileId", "downloadUrl", "sizeBytes", "name", "mimeType" ], "description": "Local transit file upload response." }, "ProviderDefinition": { "type": "object", "additionalProperties": true, "description": "Public provider catalog definition." }, "RunLog": { "type": "object", "properties": { "id": { "type": "string", "description": "Run identifier." }, "service": { "type": "string", "description": "Provider service that owns the executed action." }, "actionId": { "type": "string", "description": "Executed action id." }, "caller": { "type": "string", "description": "Runtime entry point that executed the run." }, "startedAt": { "type": "string", "description": "Start timestamp." }, "completedAt": { "type": "string", "description": "Completion timestamp." }, "durationMs": { "type": "number", "description": "Run duration in milliseconds." }, "ok": { "type": "boolean", "description": "Whether the run succeeded." }, "connectionProfile": { "type": "object", "additionalProperties": true, "description": "Provider account identity that the action used, when a connection was available." }, "connectionId": { "type": "string", "description": "Stable connection identifier used by the run." }, "runtimeTokenId": { "type": "string", "description": "Stored runtime token identifier used by the run." }, "policy": { "$ref": "#/components/schemas/PolicyDecision" }, "inputSummary": { "description": "Redacted action input summary." }, "outputSummary": { "description": "Redacted action output summary." }, "errorCode": { "type": "string", "description": "Error code when the run failed." }, "errorMessage": { "type": "string", "description": "Error message when the run failed." } }, "additionalProperties": false, "required": [ "id", "service", "actionId", "caller", "startedAt", "completedAt", "durationMs", "ok" ], "description": "Recent action run entry." }, "RunLogPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RunLog" }, "description": "Run entries for this page." }, "nextCursor": { "type": "string", "description": "Cursor for the next page, when more runs are available." } }, "additionalProperties": false, "required": [ "items" ], "description": "Paginated action run list." } } }, "servers": [ { "url": "https://capworks-api-docs.pages.dev/proxy/openconnector", "description": "文档站同源代理" }, { "url": "http://localhost:8788", "description": "本地开发" } ] }