{
  "openapi": "3.1.0",
  "info": {
    "title": "Weavz API",
    "version": "1.0.0",
    "description": "Weavz is governed app access and execution infrastructure for modern software teams.\nIt provides connection management, hosted connect flows, MCP servers, triggers,\naction execution, Filesystem, State KV, Sandbox execution, and approvals for third-party\nservices, so your product can expose secure integration workflows to SaaS apps, copilots,\nautomations, and AI agents.\n\nThe public API is designed for SaaS builders as well as internal automation: you can provision\nworkspaces, register end users, create hosted connect sessions, expose MCP servers, execute\nactions, manage triggers, and configure workspace integrations without exposing Weavz\ndashboard-only administration routes.\n\n## Authentication\n\nAuthenticate with an API key passed as a Bearer token:\n\n```\nAuthorization: Bearer wvz_...\n```\n\n## Rate Limiting\n\nAPI requests are rate-limited based on your organization's plan tier. Rate limit information\nis returned in response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.\n\n## Error Responses\n\nAll errors follow a consistent format with an error message, error code, and optional details:\n\n```json\n{\n  \"error\": \"Human-readable error message\",\n  \"code\": \"ERROR_CODE\",\n  \"details\": {}\n}\n```\n\n## API Key Scoping\n\nAPI keys can be scoped to specific workspaces via the `permissions` field. When a workspace-scoped\nkey attempts to access resources outside its allowed workspaces, or org-level routes that require\nfull org access, the API returns `403` with error code `SCOPE_DENIED`.\n",
    "contact": {
      "name": "Weavz Support",
      "url": "https://weavz.io",
      "email": "support@weavz.io"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://platform.weavz.io",
      "description": "Production server"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development server"
    }
  ],
  "tags": [
    {
      "name": "Workspaces",
      "description": "Workspace management for tenant, environment, or project isolation"
    },
    {
      "name": "Connections",
      "description": "Connection management for integrations"
    },
    {
      "name": "Connect",
      "description": "Hosted connection flow"
    },
    {
      "name": "Workspace Integrations",
      "description": "Manage integration instances on workspaces"
    },
    {
      "name": "Actions",
      "description": "Execute integration actions"
    },
    {
      "name": "Triggers",
      "description": "Enable and manage triggers"
    },
    {
      "name": "API Keys",
      "description": "API key management"
    },
    {
      "name": "MCP Servers",
      "description": "MCP server and tool management"
    },
    {
      "name": "Integrations",
      "description": "Integration metadata and property resolution"
    },
    {
      "name": "Input Partials",
      "description": "Saved parameter presets for actions and triggers"
    },
    {
      "name": "Approvals",
      "description": "Human Gates policies and approval requests for guarded action execution"
    },
    {
      "name": "Computer Sessions",
      "description": "Short-lived human viewer access for hosted computer sessions"
    },
    {
      "name": "End Users",
      "description": "End user management and connect portal"
    },
    {
      "name": "Skills",
      "description": "Optional reusable task instructions in personal and shared workspace libraries."
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "wvz_xxxxx",
        "description": "API key authentication (prefix `wvz_`)"
      }
    },
    "parameters": {
      "SkillWorkspace": {
        "name": "workspaceId",
        "in": "query",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "description": "Workspace containing the library. The API key must have access."
      },
      "SkillScope": {
        "name": "scope",
        "in": "query",
        "schema": {
          "type": "string",
          "enum": [
            "end_user",
            "workspace"
          ],
          "default": "end_user"
        },
        "description": "Personal library or shared workspace instructions."
      },
      "SkillEndUser": {
        "name": "endUserId",
        "in": "query",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "description": "Customer external end-user identity. Required for the personal end_user scope. Never an internal end-user UUID."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error",
          "code"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code",
            "enum": [
              "VALIDATION_ERROR",
              "NOT_FOUND",
              "DUPLICATE",
              "QUOTA_EXCEEDED",
              "RATE_LIMITED",
              "UNAUTHORIZED",
              "FORBIDDEN",
              "SCOPE_DENIED",
              "UNAUTHENTICATED",
              "AUTH_DISABLED",
              "NOT_MEMBER",
              "SLUG_EXISTS",
              "MISSING_FIELDS",
              "NO_UPDATES",
              "CONNECTION_NOT_FOUND",
              "CONNECTION_REQUIRED",
              "INTEGRATION_NOT_FOUND",
              "TRIGGER_NOT_FOUND",
              "ACTION_FAILED",
              "NOT_DROPDOWN",
              "NO_OPTIONS_FN",
              "OPTIONS_FAILED",
              "NOT_OAUTH2",
              "MISSING_OAUTH2_CONFIG",
              "OAUTH_ERROR",
              "ALIAS_CONFLICT",
              "MISSING_KEY",
              "STORAGE_ERROR",
              "INVALID_JSON",
              "HTTP_ERROR",
              "INTERNAL_ERROR",
              "MISSING_CODE",
              "POLLING_INTERVAL_TOO_SHORT",
              "INVALID_ADDON",
              "NOT_DYNAMIC",
              "NO_PROPS_FN",
              "RESOLVE_FAILED",
              "MISSING_CONNECTION",
              "MISSING_INTEGRATION_NAME",
              "MISSING_ID",
              "TOKEN_EXCHANGE_FAILED",
              "INVALID_CONFIG",
              "REFRESH_FAILED",
              "END_USER_NOT_FOUND",
              "AMBIGUOUS_INTEGRATION",
              "ACTION_NOT_ALLOWED",
              "PARTIAL_MISMATCH",
              "PARTIAL_NOT_FOUND",
              "ACTION_NOT_FOUND",
              "INTEGRATION_UNAVAILABLE",
              "NATIVE_RUNTIME_REQUIRED",
              "NATIVE_ACTION_UNSUPPORTED",
              "SHARD_UNAVAILABLE",
              "NO_OAUTH_APP",
              "OAUTH_APP_NOT_FOUND",
              "INVALID_OAUTH_APP",
              "SESSION_CREATE_FAILED",
              "INVALID_TOKEN",
              "MISSING_TOKEN",
              "MCP_BEARER_BLOCKS_PER_USER",
              "MCP_BEARER_DISABLED",
              "MCP_STATIC_BEARER_INCOMPATIBLE",
              "MCP_OAUTH_DISABLED",
              "INVALID_MCP_SCOPES",
              "WORKSPACE_REQUIRED",
              "AUTH_SCOPE_DENIED",
              "APPROVAL_POLICY_BLOCKED",
              "APPROVAL_POLICY_NOT_FOUND",
              "APPROVAL_NOT_FOUND",
              "APPROVAL_ALREADY_DECIDED",
              "APPROVAL_EXPIRED",
              "APPROVAL_UPDATE_CONFLICT",
              "APPROVAL_DECISION_SCOPE_REQUIRED",
              "APPROVAL_DECISION_DENIED",
              "BROWSER_SANDBOX_UNAVAILABLE",
              "BROWSER_SESSION_START_FAILED",
              "BROWSER_CONTROL_REQUIRED",
              "BROWSER_RECOVERY_REQUIRED",
              "SESSION_NOT_FOUND",
              "HANDOFF_FAILED",
              "ACTION_NOT_ENABLED",
              "ALIAS_NOT_FOUND",
              "ALREADY_INITIALIZED",
              "APPROVAL_LINK_NOT_FOUND",
              "AUTH_METHOD_REQUIRED",
              "AUTH_NOT_SUPPORTED",
              "CONNECTION_AUTH_METHOD_MISMATCH",
              "CONNECTION_CREATE_FAILED",
              "CONNECTION_MISMATCH",
              "CONNECTION_NOT_SUPPORTED",
              "CONNECTION_SCOPE_MISMATCH",
              "DUPLICATE_CONNECTION",
              "EMAIL_RATE_LIMITED",
              "END_USER_REQUIRES_WORKSPACE",
              "INTEGRATION_MISMATCH",
              "INTEGRATION_NOT_ALLOWED",
              "INTEGRATION_NOT_CONFIGURED",
              "INTEGRATION_NOT_CONNECTABLE",
              "INVALID_ACTION",
              "INVALID_AUTH_METHOD",
              "INVALID_AUTH_TYPE",
              "INVALID_CODE_EXECUTE_REQUEST",
              "INVALID_CONNECTION",
              "INVALID_INTEGRATION",
              "INVALID_REDIRECT_URI",
              "INVALID_STATUS",
              "INVALID_STRATEGY",
              "INVALID_WORKSPACE",
              "MCP_SUSPENDED",
              "MISSING_CREDENTIALS",
              "MISSING_INTEGRATION",
              "MISSING_PROPERTY",
              "MISSING_WORKSPACE",
              "MISSING_WORKSPACE_ID",
              "OAUTH_AUTHORIZATION_FAILED",
              "OAUTH_TOKEN_FAILED",
              "PARTIAL_SCOPE_MISMATCH",
              "SHARD_NOT_AVAILABLE",
              "TOKEN_EXPIRED",
              "UNSUPPORTED_AUTH_TYPE",
              "WORKSPACE_INTEGRATION_NOT_FOUND",
              "MCP_WORKSPACE_ALREADY_CONFIGURED",
              "MCP_WORKSPACE_ENDPOINT_REQUIRED",
              "MCP_WORKSPACE_IDENTITY_IN_USE"
            ]
          },
          "details": {
            "type": "object",
            "description": "Additional error context",
            "additionalProperties": true
          }
        }
      },
      "Workspace": {
        "description": "An MCP Workspace with one automatically prepared MCP endpoint.",
        "type": "object",
        "required": [
          "id",
          "orgId",
          "name",
          "slug",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "mcpServer": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/WorkspaceMcpEndpoint"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "orgId": {
            "type": "string"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "slug": {
            "type": "string",
            "minLength": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WorkspaceMcpEndpoint": {
        "type": "object",
        "required": [
          "id",
          "mode",
          "authMode",
          "endUserAccess",
          "allowWorkspaceMembers",
          "mcpEndpoint"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "mode": {
            "type": "string",
            "enum": [
              "TOOLS",
              "CODE"
            ]
          },
          "authMode": {
            "type": "string",
            "enum": [
              "oauth",
              "bearer",
              "oauth_and_bearer"
            ]
          },
          "endUserAccess": {
            "type": "string",
            "enum": [
              "restricted",
              "open"
            ]
          },
          "allowWorkspaceMembers": {
            "type": "boolean",
            "description": "Authenticated organization members may join in addition to explicitly pre-added end users. Existing endpoint policies are preserved."
          },
          "mcpEndpoint": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Connection": {
        "type": "object",
        "required": [
          "id",
          "externalId",
          "displayName",
          "integrationName",
          "type",
          "status",
          "scope",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "externalId": {
            "type": "string",
            "description": "Customer-defined connection.externalId selector"
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable connection name"
          },
          "integrationName": {
            "type": "string",
            "description": "Integration name (e.g., 'slack', 'gmail')"
          },
          "authMethodKey": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Selected integration auth method key for this credential, such as `api_key` or `oauth2`."
          },
          "type": {
            "type": "string",
            "enum": [
              "SECRET_TEXT",
              "BASIC_AUTH",
              "CUSTOM_AUTH",
              "OAUTH2",
              "PLATFORM_OAUTH2"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "ERROR",
              "EXPIRED"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "ORGANIZATION",
              "WORKSPACE",
              "USER"
            ]
          },
          "workspaceId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "endUserId": {
            "type": [
              "string",
              "null"
            ],
            "description": "The end user's external ID (your application's user identifier), or null if not user-scoped"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ConnectSession": {
        "type": "object",
        "required": [
          "id",
          "integrationName",
          "connectionName",
          "externalId",
          "status",
          "connectionId",
          "error",
          "expiresAt",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "integrationName": {
            "type": "string",
            "description": "Integration being connected"
          },
          "workspaceIntegrationId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "description": "Configured workspace integration whose auth selection this session inherits."
          },
          "authMethodKey": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Selected integration auth method key for this hosted connect session."
          },
          "oauthAppMode": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "weavz_managed",
                  "custom"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "OAuth app policy used when the selected auth method is OAuth."
          },
          "oauthAppId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "description": "Resolved OAuth app UUID used by this session when OAuth is selected. This may be a Weavz-managed platform app or a tenant-owned custom app."
          },
          "connectionName": {
            "type": "string",
            "description": "Display name for the connection"
          },
          "externalId": {
            "type": "string",
            "description": "Customer-defined connection.externalId selector"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "CONNECTING",
              "COMPLETED",
              "FAILED"
            ],
            "description": "Current session status"
          },
          "connectionId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "ID of the created connection (set when COMPLETED)"
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Error message (set when FAILED)"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AdvancedCodeWorkspaceSettings": {
        "type": "object",
        "description": "Owner-controlled Sandbox execution policy for the advanced-code workspace integration.",
        "properties": {
          "timeoutSeconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 300,
            "default": 300,
            "description": "Maximum execution time per Sandbox run."
          },
          "sandboxPersistence": {
            "type": "string",
            "enum": [
              "ephemeral",
              "persistent"
            ],
            "default": "ephemeral",
            "description": "Whether the sandbox is destroyed after each run or reused between runs."
          },
          "storageMountScope": {
            "type": "string",
            "enum": [
              "none",
              "end_user",
              "workspace",
              "external"
            ],
            "default": "none",
            "description": "Filesystem namespace mounted into the Sandbox."
          },
          "storageExternalId": {
            "type": "string",
            "description": "Required when storageMountScope is external."
          }
        }
      },
      "WorkspaceIntegrationSettings": {
        "type": "object",
        "properties": {
          "advancedCode": {
            "$ref": "#/components/schemas/AdvancedCodeWorkspaceSettings"
          },
          "persistence": {
            "$ref": "#/components/schemas/PersistenceWorkspaceSettings"
          },
          "localBrowser": {
            "$ref": "#/components/schemas/LocalBrowserWorkspaceSettings"
          }
        }
      },
      "PersistenceWorkspaceSettings": {
        "type": "object",
        "description": "Owner-controlled state and session-profile scope for stateful workspace integrations.",
        "properties": {
          "scope": {
            "type": "string",
            "enum": [
              "end_user",
              "workspace",
              "external"
            ],
            "default": "end_user",
            "description": "Persistent state namespace used by Filesystem, State KV, Agent Memory, Agent Scratchpad, Sequential Thinking, Agent Browser, Agent Browser (Stealth), Agent Browser AI, Agent Browser (Stealth AI), and Local Browser for Agents. Browser integrations use this scope for durable browser profiles and live session reuse."
          },
          "externalId": {
            "type": "string",
            "description": "Required when scope is external."
          }
        }
      },
      "LocalBrowserWorkspaceSettings": {
        "type": "object",
        "description": "Owner-controlled runtime policy for the Local Browser for Agents workspace integration.",
        "properties": {
          "runtime": {
            "type": "string",
            "enum": [
              "chrome_extension",
              "managed_profile"
            ],
            "default": "chrome_extension"
          }
        }
      },
      "WorkspaceIntegration": {
        "type": "object",
        "required": [
          "id",
          "workspaceId",
          "integrationName",
          "alias",
          "connectionStrategy",
          "connectionId",
          "displayName",
          "enabledActions",
          "settings",
          "sortOrder",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspaceId": {
            "type": "string",
            "format": "uuid"
          },
          "integrationName": {
            "type": "string",
            "description": "Catalog app slug, such as `slack`."
          },
          "alias": {
            "type": "string",
            "description": "Configured workspace integration alias agents use as the Code Mode namespace and Tool Mode tool prefix, such as `office_slack`."
          },
          "connectionStrategy": {
            "type": "string",
            "enum": [
              "fixed",
              "per_user",
              "per_user_with_fallback"
            ]
          },
          "authMethodKey": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Selected auth method for this configured integration instance. Required on create when the catalog integration exposes multiple auth options."
          },
          "oauthAppMode": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "weavz_managed",
                  "custom"
                ]
              },
              {
                "type": "null"
              }
            ],
            "description": "OAuth app policy used when `authMethodKey` selects an OAuth method. Defaults to `weavz_managed`."
          },
          "oauthAppId": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ],
            "description": "Tenant-owned custom OAuth app UUID when `oauthAppMode` is `custom`; null for Weavz-managed OAuth."
          },
          "connectionId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabledActions": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "settings": {
            "$ref": "#/components/schemas/WorkspaceIntegrationSettings"
          },
          "sortOrder": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "connectionExternalId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Customer-defined external ID of the fixed connection, when available in list responses."
          },
          "connectionDisplayName": {
            "type": [
              "string",
              "null"
            ]
          },
          "connectionStatus": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "ACTIVE",
              "ERROR",
              "EXPIRED",
              null
            ]
          }
        }
      },
      "TriggerSource": {
        "type": "object",
        "required": [
          "id",
          "orgId",
          "triggerType",
          "integrationName",
          "triggerName",
          "callbackUrl",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "orgId": {
            "type": "string"
          },
          "triggerType": {
            "type": "string",
            "enum": [
              "WEBHOOK",
              "POLLING",
              "APP_WEBHOOK"
            ]
          },
          "integrationName": {
            "type": "string"
          },
          "triggerName": {
            "type": "string"
          },
          "webhookUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "URL to receive webhooks for WEBHOOK-type triggers"
          },
          "callbackUrl": {
            "type": "string",
            "format": "uri",
            "description": "URL to deliver trigger events"
          },
          "simulate": {
            "type": "boolean",
            "description": "Whether this trigger is in simulation mode"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "workspaceId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "workspaceIntegrationId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "integrationAlias": {
            "type": [
              "string",
              "null"
            ],
            "description": "Configured integration alias, when returned after enabling a trigger."
          },
          "lastDelivery": {
            "type": [
              "object",
              "null"
            ],
            "description": "Most recent delivery observed in list responses.",
            "properties": {
              "status": {
                "type": "string"
              },
              "httpStatus": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "errorMessage": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "attempt": {
                "type": "integer"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time"
              },
              "deliveredAt": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        }
      },
      "ApiKey": {
        "type": "object",
        "required": [
          "id",
          "orgId",
          "name",
          "keyPrefix",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "orgId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "keyPrefix": {
            "type": "string",
            "description": "First 8 characters of the API key (for identification)"
          },
          "permissions": {
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "scope"
                ],
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "org"
                    ]
                  },
                  "approvals": {
                    "type": "object",
                    "description": "Optional Human Gates decision permissions.",
                    "properties": {
                      "decide": {
                        "type": "boolean",
                        "description": "Allows this key to approve, reject, or cancel Human Gates requests within its access scope."
                      }
                    }
                  }
                }
              },
              {
                "type": "object",
                "required": [
                  "scope",
                  "workspaceIds"
                ],
                "properties": {
                  "scope": {
                    "type": "string",
                    "enum": [
                      "workspace"
                    ]
                  },
                  "workspaceIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1
                  },
                  "approvals": {
                    "type": "object",
                    "description": "Optional Human Gates decision permissions scoped to the same workspaces.",
                    "properties": {
                      "decide": {
                        "type": "boolean",
                        "description": "Allows this key to approve, reject, or cancel Human Gates requests within its access scope."
                      }
                    }
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "lastUsedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expiresAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "McpServerSettings": {
        "type": "object",
        "properties": {
          "codeMode": {
            "type": "object",
            "properties": {
              "approvalWaitSeconds": {
                "type": "integer",
                "minimum": 0,
                "maximum": 60,
                "description": "Seconds to keep a Code Mode approval continuation call open while a Human Gate is pending. Defaults to 0."
              }
            }
          },
          "mcpApp": {
            "type": "object",
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "Exposes the Weavz MCP App tools and HTML resources on this server endpoint. Defaults to false unless enabled explicitly."
              }
            }
          }
        }
      },
      "McpServer": {
        "type": "object",
        "required": [
          "id",
          "orgId",
          "name",
          "mode",
          "settings",
          "createdBy",
          "createdAt",
          "updatedAt",
          "mcpEndpoint"
        ],
        "properties": {
          "isCanonical": {
            "type": "boolean",
            "description": "The primary endpoint belonging to this MCP Workspace. False identifies a legacy compatibility endpoint."
          },
          "allowWorkspaceMembers": {
            "type": "boolean",
            "description": "Allows authenticated organization members to authorize this endpoint, in addition to pre-added users."
          },
          "id": {
            "type": "string",
            "description": "Server ID (without 'srv_' prefix)"
          },
          "orgId": {
            "type": "string"
          },
          "workspaceId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "mode": {
            "type": "string",
            "enum": [
              "TOOLS",
              "CODE"
            ],
            "description": "Server mode (TOOLS for individual tools, CODE for code-mode meta-tools)"
          },
          "settings": {
            "$ref": "#/components/schemas/McpServerSettings"
          },
          "authMode": {
            "type": "string",
            "enum": [
              "oauth",
              "bearer",
              "oauth_and_bearer"
            ],
            "description": "MCP authentication mode. OAuth is recommended for interactive clients; bearer mode supports end-user scoped bearer tokens and may also have a static service token when safe."
          },
          "endUserAccess": {
            "type": "string",
            "enum": [
              "restricted",
              "open"
            ],
            "description": "Controls who can complete MCP OAuth. restricted allows pre-added workspace end users only; open creates or links an end user during OAuth sign-in."
          },
          "auth": {
            "type": "object",
            "properties": {
              "oauthEnabled": {
                "type": "boolean"
              },
              "bearerEnabled": {
                "type": "boolean",
                "description": "True when a shared static server bearer token exists."
              },
              "staticBearerEnabled": {
                "type": "boolean",
                "description": "True when a shared static server bearer token exists."
              },
              "endUserBearerTokensEnabled": {
                "type": "boolean",
                "description": "True when API-created end-user bearer tokens are accepted for this server."
              },
              "accessTokensEnabled": {
                "type": "boolean",
                "description": "True when programmatic end-user bearer tokens can be issued."
              }
            }
          },
          "createdBy": {
            "type": "string"
          },
          "endUserId": {
            "type": [
              "string",
              "null"
            ],
            "description": "The end user's external ID (your application's user identifier), or null if not user-scoped"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "mcpEndpoint": {
            "type": "string",
            "format": "uri",
            "description": "Full MCP protocol endpoint URL"
          }
        }
      },
      "McpServerTool": {
        "type": "object",
        "required": [
          "id",
          "mcpServerId",
          "integrationName",
          "integrationAlias",
          "actionName",
          "toolType",
          "sortOrder"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "mcpServerId": {
            "type": "string"
          },
          "integrationName": {
            "type": "string",
            "description": "Catalog app slug, such as `slack`."
          },
          "integrationAlias": {
            "type": "string",
            "description": "Configured alias selector for this server tool. Tool Mode names use this as the `{alias}__{action}` prefix and Code Mode exposes synced workspace integrations as `weavz.<alias>`.",
            "pattern": "^[a-z][a-z0-9_-]*$",
            "maxLength": 64
          },
          "actionName": {
            "type": "string"
          },
          "toolType": {
            "type": "string",
            "enum": [
              "ACTION"
            ]
          },
          "connectionId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "inputDefaults": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "partialIds": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Partial IDs assigned to this tool"
          },
          "sortOrder": {
            "type": "number",
            "default": 0
          },
          "sourceWorkspaceIntegrationId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "ID of the workspace integration this tool was synced from"
          }
        }
      },
      "IntegrationMetadata": {
        "type": "object",
        "required": [
          "name",
          "displayName",
          "description",
          "logoUrl",
          "categories",
          "auth",
          "authOptions",
          "actions",
          "triggers"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "displayName": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "logoUrl": {
            "type": "string",
            "format": "uri"
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "AI",
                "ANALYTICS",
                "COMMERCE",
                "COMMUNICATION",
                "CONTENT_AND_FILES",
                "CUSTOMER_SUPPORT",
                "DEVELOPER_TOOLS",
                "FINANCE",
                "FORMS_AND_SURVEYS",
                "HR_AND_RECRUITING",
                "MARKETING",
                "PROJECT_MANAGEMENT",
                "PRODUCTIVITY",
                "SALES_AND_CRM"
              ]
            }
          },
          "auth": {
            "type": "object",
            "description": "Default auth summary for integrations with auth. Use `authOptions` for canonical auth selection.",
            "properties": {
              "type": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "oauth2": {
                "type": [
                  "object",
                  "null"
                ]
              }
            }
          },
          "authOptions": {
            "type": "array",
            "description": "Canonical auth methods supported by the integration. Workspace integrations and connect sessions select one option with `authMethodKey`.",
            "items": {
              "type": "object",
              "required": [
                "key",
                "type"
              ],
              "properties": {
                "key": {
                  "type": "string",
                  "description": "Stable auth method key, such as `api_key`, `basic_auth`, `custom_auth`, `oauth2`, or a provider-specific key."
                },
                "type": {
                  "type": "string",
                  "description": "Integration auth type for this option."
                },
                "displayName": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "oauth2": {
                  "type": [
                    "object",
                    "null"
                  ]
                }
              }
            }
          },
          "actions": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          },
          "triggers": {
            "type": "object",
            "additionalProperties": {
              "type": "object"
            }
          }
        }
      },
      "InputPartial": {
        "type": "object",
        "required": [
          "id",
          "orgId",
          "workspaceId",
          "integrationName",
          "name",
          "values",
          "enforcedKeys",
          "isDefault",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "orgId": {
            "type": "string"
          },
          "workspaceId": {
            "type": "string",
            "format": "uuid"
          },
          "integrationName": {
            "type": "string"
          },
          "workspaceIntegrationId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Configured workspace integration instance this partial is scoped to."
          },
          "integrationAlias": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9_-]*$",
            "description": "Workspace integration alias this partial is scoped to."
          },
          "actionName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Action scope. Null means this partial is not action-specific."
          },
          "triggerName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Trigger scope. Null means this partial is not trigger-specific. `actionName` and `triggerName` are mutually exclusive."
          },
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500
          },
          "values": {
            "type": "object",
            "additionalProperties": true
          },
          "enforcedKeys": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Keys whose values cannot be overridden at runtime"
          },
          "isDefault": {
            "type": "boolean"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ComputerSessionAccessInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "workspaceId",
          "endUserId",
          "role"
        ],
        "properties": {
          "workspaceId": {
            "type": "string",
            "format": "uuid"
          },
          "endUserId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Your external end-user ID for the user who owns this computer session, not a Weavz internal UUID."
          },
          "role": {
            "type": "string",
            "enum": [
              "watch",
              "control"
            ],
            "description": "Human access to watch the computer or take control."
          },
          "ttlSeconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 300,
            "description": "Requested link lifetime in seconds, bounded by the computer session lifetime."
          },
          "frameOrigin": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "format": "uri",
            "description": "Exact HTTPS origin of the application embedding the viewer, without a path, query, fragment, credentials, or wildcard. HTTP is accepted only for local development."
          }
        }
      },
      "ComputerSessionAccess": {
        "type": "object",
        "required": [
          "sessionId",
          "role",
          "viewerUrl",
          "expiresAt"
        ],
        "properties": {
          "sessionId": {
            "type": "string",
            "format": "uuid"
          },
          "role": {
            "type": "string",
            "enum": [
              "watch",
              "control"
            ]
          },
          "viewerUrl": {
            "type": "string",
            "format": "uri",
            "description": "Short-lived human viewer URL containing a sensitive access capability in its fragment. Deliver it to the intended human without adding it to agent or tool context."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "frameOrigin": {
            "type": "string",
            "format": "uri",
            "description": "Canonical embedding origin when frameOrigin was requested."
          }
        }
      },
      "ApprovalReviewAccess": {
        "type": "object",
        "required": [
          "canDecide"
        ],
        "properties": {
          "canDecide": {
            "type": "boolean"
          },
          "reason": {
            "type": "string",
            "description": "Explanation when the current caller cannot decide this request."
          },
          "code": {
            "type": "string"
          }
        }
      },
      "ApprovalPolicy": {
        "type": "object",
        "required": [
          "id",
          "orgId",
          "name",
          "enabled",
          "priority",
          "sources",
          "decision",
          "riskMode",
          "timeoutSeconds",
          "defaultOnTimeout",
          "approvalAccessMode",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "orgId": {
            "type": "string"
          },
          "workspaceId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "enabled": {
            "type": "boolean"
          },
          "priority": {
            "type": "integer"
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "rest",
                "sdk",
                "mcp_tools",
                "mcp_code",
                "playground",
                "trigger"
              ]
            }
          },
          "mcpServerIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "workspaceIntegrationIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "integrationAliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "integrationNames": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "actionNames": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "connectionStrategies": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "fixed",
                "per_user",
                "per_user_with_fallback"
              ]
            }
          },
          "endUserMode": {
            "type": "string",
            "enum": [
              "any",
              "end_user_present",
              "no_end_user"
            ]
          },
          "decision": {
            "type": "string",
            "enum": [
              "require_approval",
              "notify_only",
              "block",
              "auto_approve"
            ]
          },
          "riskMode": {
            "type": "string",
            "enum": [
              "always",
              "rules",
              "model_assisted"
            ]
          },
          "rules": {
            "type": "object",
            "additionalProperties": true
          },
          "approvers": {
            "type": "array",
            "description": "Reviewer specification. Webhook approvers receive lifecycle events and a short-lived hosted approval URL.",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "org_role",
                    "dashboard_user",
                    "end_user",
                    "webhook"
                  ]
                },
                "roles": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member"
                    ]
                  }
                },
                "userIds": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "webhookUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "Public HTTPS webhook URL for webhook approvers."
                }
              },
              "additionalProperties": true
            }
          },
          "timeoutSeconds": {
            "type": "integer"
          },
          "defaultOnTimeout": {
            "type": "string",
            "enum": [
              "reject",
              "expire"
            ]
          },
          "reuseWindowSeconds": {
            "type": [
              "integer",
              "null"
            ]
          },
          "approvalAccessMode": {
            "type": "string",
            "enum": [
              "dashboard_only",
              "dashboard_and_hosted_link",
              "hosted_link_only"
            ],
            "description": "Controls whether reviewers can approve through Weavz review views, hosted bearer links, or both."
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ApprovalPolicyInput": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "workspaceId": {
            "type": "string",
            "format": "uuid",
            "description": "Optional workspace scope. Omit for an org-wide policy."
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "description": {
            "type": "string",
            "maxLength": 1000
          },
          "enabled": {
            "type": "boolean",
            "default": true
          },
          "priority": {
            "type": "integer",
            "default": 100
          },
          "sources": {
            "type": "array",
            "default": [
              "rest",
              "sdk",
              "mcp_tools",
              "mcp_code"
            ],
            "items": {
              "type": "string",
              "enum": [
                "rest",
                "sdk",
                "mcp_tools",
                "mcp_code",
                "playground",
                "trigger"
              ]
            }
          },
          "mcpServerIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "workspaceIntegrationIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "integrationAliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "integrationNames": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "actionNames": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "connectionStrategies": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "fixed",
                "per_user",
                "per_user_with_fallback"
              ]
            }
          },
          "endUserMode": {
            "type": "string",
            "enum": [
              "any",
              "end_user_present",
              "no_end_user"
            ],
            "default": "any"
          },
          "decision": {
            "type": "string",
            "enum": [
              "require_approval",
              "notify_only",
              "block",
              "auto_approve"
            ],
            "default": "require_approval"
          },
          "riskMode": {
            "type": "string",
            "enum": [
              "always",
              "rules",
              "model_assisted"
            ],
            "default": "rules"
          },
          "rules": {
            "type": "object",
            "additionalProperties": true
          },
          "approvers": {
            "type": "array",
            "description": "Reviewer specification. Use `{ \"type\": \"webhook\", \"webhookUrl\": \"https://...\" }` to receive approval lifecycle events.",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "org_role",
                    "dashboard_user",
                    "end_user",
                    "webhook"
                  ]
                },
                "roles": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": [
                      "owner",
                      "admin",
                      "member"
                    ]
                  }
                },
                "userIds": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "webhookUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "Public HTTPS webhook URL for webhook approvers."
                }
              },
              "additionalProperties": true
            }
          },
          "timeoutSeconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 2592000,
            "default": 3600
          },
          "defaultOnTimeout": {
            "type": "string",
            "enum": [
              "reject",
              "expire"
            ],
            "default": "reject"
          },
          "reuseWindowSeconds": {
            "type": "integer",
            "minimum": 0,
            "maximum": 604800
          },
          "approvalAccessMode": {
            "type": "string",
            "enum": [
              "dashboard_only",
              "dashboard_and_hosted_link",
              "hosted_link_only"
            ],
            "default": "dashboard_and_hosted_link",
            "description": "Controls whether reviewers can approve through Weavz review views, hosted bearer links, or both."
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ApprovalRequest": {
        "type": "object",
        "required": [
          "id",
          "orgId",
          "source",
          "status",
          "integrationName",
          "actionName",
          "inputHash",
          "inputPreview",
          "redactedPaths",
          "riskReasons",
          "defaultOnTimeout",
          "approvalAccessMode",
          "expiresAt",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "reviewAccess": {
            "$ref": "#/components/schemas/ApprovalReviewAccess",
            "description": "Current caller decision access, supplied by the approval detail endpoint."
          },
          "id": {
            "type": "string",
            "description": "Approval request ID."
          },
          "policyId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "orgId": {
            "type": "string"
          },
          "workspaceId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "endUserId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "source": {
            "type": "string",
            "enum": [
              "rest",
              "sdk",
              "mcp_tools",
              "mcp_code",
              "playground",
              "trigger"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "expired",
              "canceled",
              "consumed"
            ]
          },
          "mcpServerId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "mcpMode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "TOOLS",
              "CODE",
              null
            ]
          },
          "mcpAuthMode": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "oauth",
              "bearer",
              "oauth_and_bearer",
              null
            ]
          },
          "workspaceIntegrationId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "integrationName": {
            "type": "string"
          },
          "integrationAlias": {
            "type": [
              "string",
              "null"
            ]
          },
          "actionName": {
            "type": "string"
          },
          "connectionStrategy": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "fixed",
              "per_user",
              "per_user_with_fallback",
              null
            ]
          },
          "connectionScopeSummary": {
            "type": [
              "string",
              "null"
            ]
          },
          "partialIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "enforcedKeys": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "inputHash": {
            "type": "string",
            "description": "Hash of the exact resolved input and execution context."
          },
          "inputPreview": {
            "type": "object",
            "additionalProperties": true,
            "description": "Redacted preview of the final resolved input. For MCP Code Mode batch approvals, `json.type` is `mcp_code_batch_run` and includes deterministic summaries, predicted tools, code hash, and tool-surface hash."
          },
          "redactedPaths": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "riskReasons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "riskScore": {
            "type": [
              "number",
              "null"
            ]
          },
          "riskCategory": {
            "type": [
              "string",
              "null"
            ]
          },
          "approverSpec": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "defaultOnTimeout": {
            "type": "string",
            "enum": [
              "reject",
              "expire"
            ],
            "description": "Final automatic decision when the pending request reaches expiresAt without a human decision."
          },
          "approvalAccessMode": {
            "type": "string",
            "enum": [
              "dashboard_only",
              "dashboard_and_hosted_link",
              "hosted_link_only"
            ],
            "description": "Access mode captured from the matched policy when this request was created."
          },
          "approvalUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri",
            "description": "Approval URL allowed by the policy access mode."
          },
          "hostedApprovalUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "externalCorrelationId": {
            "type": [
              "string",
              "null"
            ]
          },
          "idempotencyKey": {
            "type": [
              "string",
              "null"
            ]
          },
          "requestedByType": {
            "type": [
              "string",
              "null"
            ]
          },
          "requestedById": {
            "type": [
              "string",
              "null"
            ]
          },
          "decidedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "consumedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "webhookDeliveries": {
            "type": "array",
            "description": "Recent lifecycle webhook delivery attempts, included on approval detail responses when webhook approvers are configured.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "eventType": {
                  "type": "string"
                },
                "callbackUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "attempt": {
                  "type": "integer"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "pending",
                    "success",
                    "failed",
                    "retrying"
                  ]
                },
                "httpStatus": {
                  "type": [
                    "integer",
                    "null"
                  ]
                },
                "errorMessage": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "deliveredAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              }
            }
          }
        }
      },
      "ApprovalCodeRunToolPlanItem": {
        "type": "object",
        "properties": {
          "integrationName": {
            "type": "string"
          },
          "integrationAlias": {
            "type": "string"
          },
          "actionName": {
            "type": "string"
          },
          "namespace": {
            "type": "string"
          },
          "matched": {
            "type": "boolean"
          },
          "approvalPolicyId": {
            "type": "string"
          },
          "approvalPolicyName": {
            "type": "string"
          },
          "approvalAccessMode": {
            "type": "string",
            "enum": [
              "dashboard_only",
              "dashboard_and_hosted_link",
              "hosted_link_only"
            ]
          }
        }
      },
      "ApprovalCodeRunGroup": {
        "type": "object",
        "properties": {
          "approvalPolicyId": {
            "type": "string"
          },
          "approvalPolicyName": {
            "type": "string"
          },
          "approvalAccessMode": {
            "type": "string",
            "enum": [
              "dashboard_only",
              "dashboard_and_hosted_link",
              "hosted_link_only"
            ]
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApprovalCodeRunToolPlanItem"
            }
          }
        }
      },
      "ApprovalCodeRunPreview": {
        "type": "object",
        "description": "Structured redacted reviewer context for MCP Code Mode approval requests.",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "mcp_code_batch_run"
            ]
          },
          "codeRunId": {
            "type": "string",
            "description": "Stable correlation ID for approvals created by the same Code Mode run."
          },
          "serverId": {
            "type": "string"
          },
          "serverName": {
            "type": "string"
          },
          "workspaceId": {
            "type": [
              "string",
              "null"
            ]
          },
          "code": {
            "type": "string",
            "description": "Stored Code Mode source shown only when present in the redacted preview."
          },
          "codeHash": {
            "type": "string"
          },
          "toolSurfaceHash": {
            "type": "string"
          },
          "intentSummary": {
            "type": "string"
          },
          "impactSummary": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "predictedTools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApprovalCodeRunToolPlanItem"
            }
          },
          "approvalRequiredTools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApprovalCodeRunToolPlanItem"
            }
          },
          "approvalGroups": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApprovalCodeRunGroup"
            }
          },
          "availableApps": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "integrationName": {
                  "type": "string"
                },
                "integrationAlias": {
                  "type": "string"
                },
                "actionCount": {
                  "type": "integer"
                }
              }
            }
          },
          "externalDomains": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "storageIndicators": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "analysisConfidence": {
            "type": "string",
            "enum": [
              "exact",
              "partial",
              "dynamic"
            ]
          },
          "dynamicSignals": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "triggeredAction": {
            "type": "object",
            "properties": {
              "integrationName": {
                "type": "string"
              },
              "integrationAlias": {
                "type": "string"
              },
              "actionName": {
                "type": "string"
              },
              "input": {}
            }
          }
        }
      },
      "ApprovalWebhookPayload": {
        "type": "object",
        "description": "Payload sent to webhook approvers for approval lifecycle events.",
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "approval.requested",
              "approval.approved",
              "approval.rejected",
              "approval.canceled",
              "approval.expired"
            ]
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "approval": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ApprovalRequest"
              },
              {
                "type": "object",
                "properties": {
                  "api": {
                    "type": "object",
                    "properties": {
                      "detailUrl": {
                        "type": "string",
                        "format": "uri"
                      },
                      "approveUrl": {
                        "type": "string",
                        "format": "uri"
                      },
                      "rejectUrl": {
                        "type": "string",
                        "format": "uri"
                      },
                      "cancelUrl": {
                        "type": "string",
                        "format": "uri"
                      }
                    }
                  },
                  "codeRun": {
                    "$ref": "#/components/schemas/ApprovalCodeRunPreview"
                  }
                }
              }
            ]
          },
          "context": {
            "type": "object",
            "additionalProperties": true,
            "description": "Denormalized workspace, end user, MCP server, tool, policy, and retry context for customer-owned approval UIs."
          },
          "receipt": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "decision": {
            "type": "object",
            "properties": {
              "reason": {
                "type": "string"
              },
              "metadata": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "ApprovalRequiredResult": {
        "type": "object",
        "required": [
          "success",
          "status",
          "approval"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "approval_required"
            ]
          },
          "approval": {
            "type": "object",
            "required": [
              "id",
              "status",
              "expiresAt",
              "retry"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "policyId": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "pending"
                ]
              },
              "approvalAccessMode": {
                "type": "string",
                "enum": [
                  "dashboard_only",
                  "dashboard_and_hosted_link",
                  "hosted_link_only"
                ]
              },
              "approvalUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "hostedApprovalUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uri"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "retry": {
                "type": "object",
                "properties": {
                  "idempotencyKey": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            }
          }
        }
      },
      "ApprovalDecisionResult": {
        "type": "object",
        "required": [
          "approval",
          "receipt"
        ],
        "properties": {
          "approval": {
            "$ref": "#/components/schemas/ApprovalRequest"
          },
          "receipt": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "EndUser": {
        "type": "object",
        "required": [
          "id",
          "workspaceId",
          "type",
          "connectionCount",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "workspaceId": {
            "type": "string",
            "format": "uuid"
          },
          "externalId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Your application's end-user identifier (endUser.externalId)"
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable display name"
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email",
            "description": "End user email address"
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "description": "Arbitrary metadata attached to the end user"
          },
          "connectionCount": {
            "type": "integer",
            "description": "Number of connections owned by this end user"
          },
          "type": {
            "type": "string",
            "enum": [
              "external",
              "member"
            ],
            "description": "Whether this end user is external or a dashboard member"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SkillLibrary": {
        "type": "object",
        "required": [
          "workspaceId"
        ],
        "properties": {
          "workspaceId": {
            "type": "string",
            "format": "uuid"
          },
          "scope": {
            "type": "string",
            "enum": [
              "end_user",
              "workspace"
            ],
            "default": "end_user"
          },
          "endUserId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255,
            "description": "Customer external end-user identity, required for a personal library. Shared workspace libraries do not have an owner selector."
          }
        }
      },
      "SkillMetadata": {
        "type": "object",
        "required": [
          "id",
          "workspaceId",
          "scope",
          "slug",
          "name",
          "description",
          "tags",
          "enabled",
          "version",
          "createdAt",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "readOnly": true
          },
          "workspaceId": {
            "type": "string",
            "format": "uuid"
          },
          "scope": {
            "type": "string",
            "enum": [
              "end_user",
              "workspace"
            ]
          },
          "slug": {
            "type": "string",
            "maxLength": 64
          },
          "name": {
            "type": "string",
            "maxLength": 120
          },
          "description": {
            "type": "string",
            "maxLength": 500
          },
          "tags": {
            "type": "array",
            "maxItems": 12,
            "items": {
              "type": "string",
              "maxLength": 32
            }
          },
          "enabled": {
            "type": "boolean"
          },
          "version": {
            "type": "integer",
            "minimum": 1,
            "readOnly": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Skill": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SkillMetadata"
          },
          {
            "type": "object",
            "required": [
              "markdown"
            ],
            "properties": {
              "markdown": {
                "type": "string",
                "description": "User-authored SKILL.md instructions. Returned only by an explicit read or successful write. Reading does not grant app permissions or run actions."
              }
            }
          }
        ]
      },
      "CreateSkillInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SkillLibrary"
          },
          {
            "type": "object",
            "required": [
              "slug",
              "name",
              "markdown"
            ],
            "properties": {
              "slug": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "pattern": "^[a-z0-9][a-z0-9-]*$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "description": {
                "type": "string",
                "maxLength": 500,
                "default": ""
              },
              "markdown": {
                "type": "string",
                "minLength": 1,
                "maxLength": 65536,
                "description": "At most 64 KiB of UTF-8 encoded instructions."
              },
              "tags": {
                "type": "array",
                "maxItems": 12,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 32
                }
              },
              "enabled": {
                "type": "boolean",
                "default": true
              }
            }
          }
        ]
      },
      "UpdateSkillInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/SkillLibrary"
          },
          {
            "type": "object",
            "required": [
              "expectedVersion"
            ],
            "description": "Include at least one content field. Scope and owner select the existing library and cannot be changed. Copy a skill to share it in a different library.",
            "properties": {
              "expectedVersion": {
                "type": "integer",
                "minimum": 1
              },
              "slug": {
                "type": "string",
                "minLength": 1,
                "maxLength": 64,
                "pattern": "^[a-z0-9][a-z0-9-]*$"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "description": {
                "type": "string",
                "maxLength": 500
              },
              "markdown": {
                "type": "string",
                "minLength": 1,
                "maxLength": 65536,
                "description": "At most 64 KiB of UTF-8 encoded instructions."
              },
              "tags": {
                "type": "array",
                "maxItems": 12,
                "items": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 32
                }
              },
              "enabled": {
                "type": "boolean"
              }
            }
          }
        ]
      },
      "SkillResponse": {
        "type": "object",
        "required": [
          "skill",
          "permissions"
        ],
        "properties": {
          "skill": {
            "$ref": "#/components/schemas/Skill"
          },
          "permissions": {
            "type": "object",
            "required": [
              "canWrite"
            ],
            "properties": {
              "canWrite": {
                "type": "boolean"
              }
            }
          },
          "instructionNotice": {
            "type": "string",
            "description": "Identifies the content as user-authored instructions, not authorization."
          }
        }
      },
      "SkillListResponse": {
        "type": "object",
        "required": [
          "skills",
          "pagination",
          "permissions"
        ],
        "description": "Metadata only. Skill instructions require an explicit read.",
        "properties": {
          "skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SkillMetadata"
            }
          },
          "pagination": {
            "type": "object",
            "required": [
              "limit",
              "offset",
              "total"
            ],
            "properties": {
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            }
          },
          "permissions": {
            "type": "object",
            "required": [
              "canWrite"
            ],
            "properties": {
              "canWrite": {
                "type": "boolean"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/workspaces": {
      "post": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Create an MCP Workspace and its endpoint",
        "operationId": "createWorkspace",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "slug": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50,
                    "pattern": "^[a-z0-9][a-z0-9-]*$",
                    "description": "Optional. A unique slug is generated when omitted."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Workspace created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspace": {
                      "$ref": "#/components/schemas/Workspace"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Workspace slug already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Workspaces"
        ],
        "summary": "List all workspaces",
        "operationId": "listWorkspaces",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "includeSuspended",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of workspaces",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspaces": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Workspace"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workspaces/{id}": {
      "get": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Get workspace by ID",
        "operationId": "getWorkspace",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "workspace": {
                      "$ref": "#/components/schemas/Workspace"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Workspace not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Update workspace",
        "operationId": "updateWorkspace",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "slug": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 50,
                    "pattern": "^[a-z0-9][a-z0-9-]*$"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workspace updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "workspace"
                  ],
                  "properties": {
                    "workspace": {
                      "$ref": "#/components/schemas/Workspace"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or no fields to update",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Workspace not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Workspace slug already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Delete a workspace",
        "operationId": "deleteWorkspace",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Workspace not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/connections": {
      "get": {
        "tags": [
          "Connections"
        ],
        "summary": "List connections",
        "operationId": "listConnections",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "description": "Optional connection ID to fetch a single connection",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "includeSuspended",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of connections or single connection",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "connections": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Connection"
                          }
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "connection": {
                          "$ref": "#/components/schemas/Connection"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Connection not found (when id query param is provided)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Workspace-scoped API keys list only resources in their allowed workspaces. Org-wide resources require an org-wide API key."
      },
      "post": {
        "tags": [
          "Connections"
        ],
        "summary": "Create a new connection",
        "operationId": "createConnection",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "type",
                  "externalId",
                  "displayName",
                  "integrationName"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "SECRET_TEXT",
                      "BASIC_AUTH",
                      "CUSTOM_AUTH",
                      "OAUTH2",
                      "PLATFORM_OAUTH2"
                    ]
                  },
                  "externalId": {
                    "type": "string",
                    "minLength": 1
                  },
                  "displayName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key for this credential. Required when the integration exposes multiple compatible auth methods; defaults from `type` for single-auth integrations."
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Required for WORKSPACE or USER scope, when endUserId is set, and for workspace-scoped API keys."
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The API resolves this to the internal end user record. Used for per-user connection resolution and for stateful workspace integrations, including browser profile reuse, when the targeted workspace integration's persistence policy is end_user. Creating a new identity uses the plan’s end-user allowance. Existing identities can connect more accounts when that allowance is full."
                  },
                  "scope": {
                    "type": "string",
                    "enum": [
                      "ORGANIZATION",
                      "WORKSPACE",
                      "USER"
                    ]
                  },
                  "oauthAppId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Tenant-owned custom OAuth app UUID to use for OAUTH2/PLATFORM_OAUTH2 connections. Omit to use the Weavz-managed OAuth app."
                  },
                  "secretText": {
                    "type": "string",
                    "description": "For SECRET_TEXT type"
                  },
                  "username": {
                    "type": "string",
                    "description": "For BASIC_AUTH type"
                  },
                  "password": {
                    "type": "string",
                    "description": "For BASIC_AUTH type"
                  },
                  "props": {
                    "type": "object",
                    "description": "For CUSTOM_AUTH type",
                    "additionalProperties": true
                  },
                  "accessToken": {
                    "type": "string",
                    "description": "For OAUTH2/PLATFORM_OAUTH2 type"
                  },
                  "refreshToken": {
                    "type": "string",
                    "description": "For OAUTH2/PLATFORM_OAUTH2 type"
                  },
                  "tokenType": {
                    "type": "string",
                    "description": "For OAUTH2/PLATFORM_OAUTH2 type"
                  },
                  "expiresIn": {
                    "type": "integer",
                    "description": "For OAUTH2/PLATFORM_OAUTH2 type"
                  },
                  "scope_oauth": {
                    "type": "string",
                    "description": "For OAUTH2/PLATFORM_OAUTH2 type"
                  },
                  "data": {
                    "type": "object",
                    "description": "For OAUTH2/PLATFORM_OAUTH2 type",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Connection created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connection": {
                      "$ref": "#/components/schemas/Connection"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Connection with this externalId already exists",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Organization-wide connections require an org-wide API key. Workspace-scoped API keys must supply an allowed workspaceId. End-user connections require workspaceId; USER scope also requires endUserId."
      }
    },
    "/api/v1/connections/{id}": {
      "delete": {
        "tags": [
          "Connections"
        ],
        "summary": "Delete a connection",
        "operationId": "deleteConnection",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Connection deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Connection not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/connections/resolve": {
      "post": {
        "tags": [
          "Connections"
        ],
        "summary": "Resolve a connection by integration and external ID",
        "operationId": "resolveConnection",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationName",
                  "workspaceId"
                ],
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "externalId": {
                    "type": "string"
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Optional auth method key to disambiguate multiple credentials for the same integration and externalId."
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The API resolves this to the internal end user record. Used for per-user connection resolution and for stateful workspace integrations, including browser profile reuse, when the targeted workspace integration's persistence policy is end_user."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Connection resolved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connection": {
                      "$ref": "#/components/schemas/Connection"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Connection not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/connect/token": {
      "post": {
        "tags": [
          "Connect"
        ],
        "summary": "Create a connect session",
        "description": "Creates a hosted connect session for a specific integration. Returns a short-lived token\nand a `connectUrl` that can be opened in a popup or browser to complete the connection flow.\nSupports all auth types: OAuth2, API key, basic auth, and custom auth.\n",
        "operationId": "connectCreateToken",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationName",
                  "connectionName",
                  "externalId",
                  "workspaceId"
                ],
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "description": "Name of the integration to connect",
                    "minLength": 1
                  },
                  "connectionName": {
                    "type": "string",
                    "description": "Display name for the connection",
                    "minLength": 1
                  },
                  "externalId": {
                    "type": "string",
                    "description": "Unique identifier for the connection",
                    "minLength": 1
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The API resolves this to the internal end user record. Used for per-user connection resolution and for stateful workspace integrations, including browser profile reuse, when the targeted workspace integration's persistence policy is end_user. Creating a new identity uses the plan’s end-user allowance. Existing identities can connect more accounts when that allowance is full."
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Workspace to scope the connection to"
                  },
                  "workspaceIntegrationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Configured workspace integration to connect. When provided, hosted connect inherits its `authMethodKey` and OAuth app policy."
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key to use when connecting by `integrationName`. Required when multiple auth options exist and no `workspaceIntegrationId` is provided."
                  },
                  "scope": {
                    "type": "string",
                    "enum": [
                      "ORGANIZATION",
                      "WORKSPACE",
                      "USER"
                    ],
                    "description": "Connection scope (default ORGANIZATION)"
                  },
                  "oauthAppMode": {
                    "type": "string",
                    "enum": [
                      "weavz_managed",
                      "custom"
                    ],
                    "description": "OAuth app policy for OAuth auth methods. Defaults to `weavz_managed`."
                  },
                  "oauthAppId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Tenant-owned custom OAuth app UUID. Required when `oauthAppMode` is `custom`; omit for Weavz-managed OAuth."
                  },
                  "successRedirectUri": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL to redirect to after successful connection (for redirect mode)"
                  },
                  "errorRedirectUri": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL to redirect to on error (for redirect mode)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Connect session created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "description": "Short-lived connect token (cst_...)"
                    },
                    "connectUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "URL to open in popup or browser"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "description": "Token expiration time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or no OAuth app configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/connect/session/{sessionId}": {
      "get": {
        "tags": [
          "Connect"
        ],
        "summary": "Get connect session status",
        "description": "Poll for the current status of a connect session. Returns PENDING, CONNECTING, COMPLETED, or FAILED.",
        "operationId": "connectGetSession",
        "parameters": [
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Session status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "session": {
                      "$ref": "#/components/schemas/ConnectSession"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Access denied (wrong org)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Session not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/connect/session/poll": {
      "post": {
        "tags": [
          "Connect"
        ],
        "summary": "Poll connect session status by token",
        "description": "Token-authenticated polling for hosted connect sessions. Use the `cst_` token returned by `POST /api/v1/connect/token`.",
        "operationId": "connectPollSession",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string",
                    "description": "Connect token returned by create token."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Session status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "connectionId",
                    "integrationName",
                    "externalId",
                    "error"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "PENDING",
                        "CONNECTING",
                        "COMPLETED",
                        "FAILED"
                      ]
                    },
                    "connectionId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uuid"
                    },
                    "integrationName": {
                      "type": "string"
                    },
                    "workspaceIntegrationId": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "uuid"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "authMethodKey": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "oauthAppMode": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "weavz_managed",
                            "custom"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "oauthAppId": {
                      "anyOf": [
                        {
                          "type": "string",
                          "format": "uuid"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "externalId": {
                      "type": "string"
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Token missing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workspaces/{workspaceId}/integrations": {
      "get": {
        "tags": [
          "Workspace Integrations"
        ],
        "summary": "List workspace integrations",
        "operationId": "listWorkspaceIntegrations",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of workspace integrations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "integrations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WorkspaceIntegration"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Workspace not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Workspace Integrations"
        ],
        "summary": "Add integration to workspace",
        "operationId": "addWorkspaceIntegration",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationName"
                ],
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "alias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$",
                    "description": "Configured workspace integration alias. Agents use this as `weavz.<alias>` in Code Mode and `{alias}__{action}` in Tool Mode. Prefer purpose-readable names such as `office_slack`, `support_slack_bot`, `customer_gmail`, or `billing_stripe`. Defaults to `integrationName` when omitted."
                  },
                  "connectionStrategy": {
                    "type": "string",
                    "enum": [
                      "fixed",
                      "per_user",
                      "per_user_with_fallback"
                    ],
                    "default": "fixed"
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key to use for this workspace integration. Required when the catalog integration exposes multiple auth options."
                  },
                  "oauthAppMode": {
                    "type": "string",
                    "enum": [
                      "weavz_managed",
                      "custom"
                    ],
                    "description": "OAuth app policy when `authMethodKey` selects an OAuth auth option. Defaults to `weavz_managed`."
                  },
                  "oauthAppId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Tenant-owned custom OAuth app UUID. Required when `oauthAppMode` is `custom`; omit for Weavz-managed OAuth."
                  },
                  "connectionId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Connection ID (required for fixed and per_user_with_fallback strategies)"
                  },
                  "displayName": {
                    "type": "string"
                  },
                  "enabledActions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of enabled action names (null means all actions)"
                  },
                  "settings": {
                    "$ref": "#/components/schemas/WorkspaceIntegrationSettings"
                  },
                  "sortOrder": {
                    "type": "integer",
                    "default": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Workspace integration added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "integration": {
                      "$ref": "#/components/schemas/WorkspaceIntegration"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Workspace not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Integration alias already exists on this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workspaces/{workspaceId}/integrations/{id}": {
      "patch": {
        "tags": [
          "Workspace Integrations"
        ],
        "summary": "Update workspace integration",
        "operationId": "updateWorkspaceIntegration",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "alias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$"
                  },
                  "connectionStrategy": {
                    "type": "string",
                    "enum": [
                      "fixed",
                      "per_user",
                      "per_user_with_fallback"
                    ]
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key to use for this workspace integration. Required when switching an integration with multiple auth options."
                  },
                  "oauthAppMode": {
                    "anyOf": [
                      {
                        "type": "string",
                        "enum": [
                          "weavz_managed",
                          "custom"
                        ]
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "OAuth app policy when `authMethodKey` selects an OAuth auth option. Defaults to `weavz_managed`."
                  },
                  "oauthAppId": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uuid"
                      },
                      {
                        "type": "null"
                      }
                    ],
                    "description": "Tenant-owned custom OAuth app UUID. Required when `oauthAppMode` is `custom`; omit for Weavz-managed OAuth."
                  },
                  "connectionId": {
                    "anyOf": [
                      {
                        "type": "string",
                        "format": "uuid"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "displayName": {
                    "anyOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "enabledActions": {
                    "anyOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "settings": {
                    "anyOf": [
                      {
                        "$ref": "#/components/schemas/WorkspaceIntegrationSettings"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "sortOrder": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workspace integration updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "integration": {
                      "$ref": "#/components/schemas/WorkspaceIntegration"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Workspace integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Alias conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Workspace Integrations"
        ],
        "summary": "Remove workspace integration",
        "operationId": "deleteWorkspaceIntegration",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Workspace integration removed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Workspace integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/actions/execute": {
      "post": {
        "tags": [
          "Actions"
        ],
        "summary": "Execute an integration action",
        "operationId": "executeAction",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationName",
                  "actionName",
                  "workspaceId"
                ],
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "actionName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "input": {
                    "type": "object",
                    "default": {},
                    "additionalProperties": true
                  },
                  "connectionExternalId": {
                    "type": "string"
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key to disambiguate direct credential resolution when an integration supports multiple auth methods."
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "workspaceIntegrationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Configured workspace integration instance to use for connection strategy and partial resolution."
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The API resolves this to the internal end user record. Used for per-user connection resolution and for stateful workspace integrations, including browser profile reuse, when the targeted workspace integration's persistence policy is end_user."
                  },
                  "integrationAlias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$",
                    "description": "Configured workspace integration alias to resolve connection strategy, partials, and action settings when `workspaceIntegrationId` is not provided."
                  },
                  "partialIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Partial IDs or names to apply. If omitted, default partials auto-resolve. Send an empty array to run without defaults."
                  },
                  "idempotencyKey": {
                    "type": "string",
                    "description": "Stable key for retrying an approval-gated action after approval."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action executed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "success",
                    "output",
                    "duration"
                  ],
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "output": {
                      "description": "Integration action output. Shape depends on the action."
                    },
                    "duration": {
                      "type": "number",
                      "description": "Action execution time in milliseconds."
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Action is waiting for approval",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApprovalRequiredResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or action failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Monthly action limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approval-policies": {
      "post": {
        "tags": [
          "Approvals"
        ],
        "summary": "Create an approval policy",
        "operationId": "createApprovalPolicy",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApprovalPolicyInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Approval policy created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "policy": {
                      "$ref": "#/components/schemas/ApprovalPolicy"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key does not have access to the requested workspace or org scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Approvals"
        ],
        "summary": "List approval policies",
        "operationId": "listApprovalPolicies",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter to a workspace. Workspace-scoped API keys only see policies for allowed workspaces."
          }
        ],
        "responses": {
          "200": {
            "description": "Approval policies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "policies",
                    "total"
                  ],
                  "properties": {
                    "policies": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApprovalPolicy"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approval-policies/test": {
      "post": {
        "tags": [
          "Approvals"
        ],
        "summary": "Test an approval policy against an execution context",
        "operationId": "testApprovalPolicy",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "policy",
                  "context"
                ],
                "properties": {
                  "policy": {
                    "$ref": "#/components/schemas/ApprovalPolicyInput"
                  },
                  "context": {
                    "type": "object",
                    "required": [
                      "integrationName",
                      "actionName"
                    ],
                    "properties": {
                      "workspaceId": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "source": {
                        "type": "string",
                        "enum": [
                          "rest",
                          "sdk",
                          "mcp_tools",
                          "mcp_code",
                          "playground",
                          "trigger"
                        ]
                      },
                      "integrationName": {
                        "type": "string"
                      },
                      "integrationAlias": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "actionName": {
                        "type": "string"
                      },
                      "connectionStrategy": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "enum": [
                          "fixed",
                          "per_user",
                          "per_user_with_fallback",
                          null
                        ]
                      },
                      "input": {
                        "type": "object",
                        "additionalProperties": true
                      },
                      "idempotencyKey": {
                        "type": [
                          "string",
                          "null"
                        ]
                      },
                      "actionCategories": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Policy evaluation result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "decision": {
                      "type": "string",
                      "enum": [
                        "allow",
                        "require_approval",
                        "notify_only",
                        "block",
                        "auto_approve"
                      ]
                    },
                    "matched": {
                      "type": "boolean"
                    },
                    "reasons": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approval-policies/{id}": {
      "get": {
        "tags": [
          "Approvals"
        ],
        "summary": "Get an approval policy",
        "operationId": "getApprovalPolicy",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Approval policy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "policy": {
                      "$ref": "#/components/schemas/ApprovalPolicy"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Approval policy not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Approvals"
        ],
        "summary": "Update an approval policy",
        "operationId": "updateApprovalPolicy",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Partial approval policy update. Omitted fields retain their saved values.",
                "properties": {
                  "workspaceId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "Set null to use an organization-wide policy. Omit to retain its current workspace."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  },
                  "description": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "priority": {
                    "type": "integer"
                  },
                  "sources": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "rest",
                        "sdk",
                        "mcp_tools",
                        "mcp_code",
                        "playground",
                        "trigger"
                      ]
                    }
                  },
                  "mcpServerIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "workspaceIntegrationIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "integrationAliases": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "integrationNames": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "actionNames": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "connectionStrategies": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "fixed",
                        "per_user",
                        "per_user_with_fallback"
                      ]
                    }
                  },
                  "endUserMode": {
                    "type": "string",
                    "enum": [
                      "any",
                      "end_user_present",
                      "no_end_user"
                    ]
                  },
                  "decision": {
                    "type": "string",
                    "enum": [
                      "require_approval",
                      "notify_only",
                      "block",
                      "auto_approve"
                    ]
                  },
                  "riskMode": {
                    "type": "string",
                    "enum": [
                      "always",
                      "rules",
                      "model_assisted"
                    ]
                  },
                  "rules": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "approvers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  },
                  "timeoutSeconds": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 2592000
                  },
                  "defaultOnTimeout": {
                    "type": "string",
                    "enum": [
                      "reject",
                      "expire"
                    ]
                  },
                  "approvalAccessMode": {
                    "type": "string",
                    "enum": [
                      "dashboard_only",
                      "dashboard_and_hosted_link",
                      "hosted_link_only"
                    ]
                  },
                  "reuseWindowSeconds": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 604800
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval policy updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "policy": {
                      "$ref": "#/components/schemas/ApprovalPolicy"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Approvals"
        ],
        "summary": "Delete an approval policy",
        "operationId": "deleteApprovalPolicy",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Approval policy deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approvals": {
      "get": {
        "tags": [
          "Approvals"
        ],
        "summary": "List approval requests",
        "operationId": "listApprovals",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "approved",
                "rejected",
                "expired",
                "canceled",
                "consumed",
                "history"
              ],
              "description": "Use pending for active requests or history for completed and timed-out requests."
            }
          },
          {
            "name": "source",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "rest",
                "sdk",
                "mcp_tools",
                "mcp_code",
                "playground",
                "trigger"
              ]
            }
          },
          {
            "name": "integrationName",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "actionName",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Opaque nextCursor returned by the previous page. Keep the same filters when requesting another page."
          }
        ],
        "responses": {
          "200": {
            "description": "Approval requests",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "approvals",
                    "total",
                    "nextCursor"
                  ],
                  "properties": {
                    "approvals": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApprovalRequest"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "description": "Number of requests returned on this page."
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Cursor for the next page, or null when no more requests match."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query or cursor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approvals/{id}": {
      "get": {
        "tags": [
          "Approvals"
        ],
        "summary": "Get an approval request",
        "operationId": "getApproval",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Approval request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "approval": {
                      "$ref": "#/components/schemas/ApprovalRequest"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approvals/{id}/approve": {
      "post": {
        "tags": [
          "Approvals"
        ],
        "summary": "Approve an approval request",
        "operationId": "approveApproval",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval decision result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApprovalDecisionResult"
                }
              }
            }
          },
          "403": {
            "description": "API key lacks Human Gates decision permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approvals/{id}/reject": {
      "post": {
        "tags": [
          "Approvals"
        ],
        "summary": "Reject an approval request",
        "operationId": "rejectApproval",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval decision result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApprovalDecisionResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/approvals/{id}/cancel": {
      "post": {
        "tags": [
          "Approvals"
        ],
        "summary": "Cancel an approval request",
        "operationId": "cancelApproval",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "type": "string",
                    "maxLength": 2000
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval decision result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApprovalDecisionResult"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/partials": {
      "post": {
        "tags": [
          "Input Partials"
        ],
        "summary": "Create an input partial",
        "operationId": "createPartial",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "workspaceId",
                  "integrationName",
                  "name"
                ],
                "properties": {
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "workspaceIntegrationId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "Configured workspace integration instance to scope the partial to. Recommended when the same integration is configured more than once."
                  },
                  "integrationAlias": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$",
                    "description": "Workspace integration alias to scope the partial to. Use with workspaceId when workspaceIntegrationId is not provided."
                  },
                  "actionName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Action scope. Omit for integration-wide or trigger-scoped partials."
                  },
                  "triggerName": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Trigger scope. Omit for integration-wide or action-scoped partials. `actionName` and `triggerName` are mutually exclusive."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500
                  },
                  "values": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "enforcedKeys": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Keys whose values cannot be overridden at runtime"
                  },
                  "isDefault": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Partial created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "partial": {
                      "$ref": "#/components/schemas/InputPartial"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate partial name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "Input Partials"
        ],
        "summary": "List input partials",
        "operationId": "listPartials",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "integrationName",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "workspaceIntegrationId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter to partials for one configured workspace integration."
          },
          {
            "name": "integrationAlias",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "pattern": "^[a-z][a-z0-9_-]*$"
            },
            "description": "Filter to partials for one workspace integration alias. Use either workspaceIntegrationId or integrationAlias, not both."
          },
          {
            "name": "actionName",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "triggerName",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of input partials",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "partials": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/InputPartial"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/partials/{id}": {
      "get": {
        "tags": [
          "Input Partials"
        ],
        "summary": "Get an input partial",
        "operationId": "getPartial",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Input partial details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "partial": {
                      "$ref": "#/components/schemas/InputPartial"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Partial not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Input Partials"
        ],
        "summary": "Update an input partial",
        "operationId": "updatePartial",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500
                  },
                  "values": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "enforcedKeys": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "isDefault": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Partial updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "partial": {
                      "$ref": "#/components/schemas/InputPartial"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or no updates provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Partial not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Duplicate partial name",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Input Partials"
        ],
        "summary": "Delete an input partial",
        "operationId": "deletePartial",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Partial deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Partial not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/partials/{id}/set-default": {
      "post": {
        "tags": [
          "Input Partials"
        ],
        "summary": "Set or unset a partial as default",
        "operationId": "setPartialDefault",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "isDefault"
                ],
                "properties": {
                  "isDefault": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Default status updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "partial": {
                      "$ref": "#/components/schemas/InputPartial"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Partial not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/triggers/enable": {
      "post": {
        "tags": [
          "Triggers"
        ],
        "summary": "Enable a trigger",
        "operationId": "enableTrigger",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationName",
                  "triggerName",
                  "callbackUrl",
                  "workspaceId"
                ],
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "triggerName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "callbackUrl": {
                    "type": "string",
                    "format": "uri"
                  },
                  "callbackHeaders": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "callbackMetadata": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "connectionExternalId": {
                    "type": "string"
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key to disambiguate direct credential resolution when an integration supports multiple auth methods."
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "workspaceIntegrationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Configured workspace integration instance to use for connection strategy resolution."
                  },
                  "integrationAlias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$",
                    "description": "Configured workspace integration alias to use when `workspaceIntegrationId` is not provided."
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The API resolves this to the internal end user record. Used for per-user connection resolution and for stateful workspace integrations, including browser profile reuse, when the targeted workspace integration's persistence policy is end_user."
                  },
                  "input": {
                    "type": "object",
                    "default": {},
                    "additionalProperties": true
                  },
                  "partialIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Partial IDs or names to apply. If omitted, default partials auto-resolve. Send an empty array to run without defaults."
                  },
                  "pollingIntervalMinutes": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1440,
                    "description": "Polling interval in minutes (only for polling triggers). Minimum depends on plan."
                  },
                  "simulate": {
                    "type": "boolean",
                    "description": "Enable simulation mode for testing"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Trigger enabled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "triggerSource": {
                      "$ref": "#/components/schemas/TriggerSource"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Trigger limit reached or polling interval too short",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Trigger not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/triggers": {
      "get": {
        "tags": [
          "Triggers"
        ],
        "summary": "List all triggers",
        "operationId": "listTriggers",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of triggers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "triggers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TriggerSource"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/triggers/disable": {
      "post": {
        "tags": [
          "Triggers"
        ],
        "summary": "Disable a trigger",
        "operationId": "disableTrigger",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "triggerSourceId"
                ],
                "properties": {
                  "triggerSourceId": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trigger disabled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "disabled": {
                      "type": "boolean"
                    },
                    "triggerSourceId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Trigger source not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/triggers/test": {
      "post": {
        "tags": [
          "Triggers"
        ],
        "summary": "Get sample data for a trigger",
        "operationId": "testTrigger",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationName",
                  "triggerName"
                ],
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "triggerName": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Trigger sample data",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "sampleData": {
                      "type": "object",
                      "additionalProperties": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Integration or trigger not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/api-keys": {
      "post": {
        "tags": [
          "API Keys"
        ],
        "summary": "Create a new API key",
        "operationId": "createApiKey",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "permissions": {
                    "oneOf": [
                      {
                        "type": "object",
                        "required": [
                          "scope"
                        ],
                        "properties": {
                          "scope": {
                            "type": "string",
                            "enum": [
                              "org"
                            ]
                          },
                          "approvals": {
                            "type": "object",
                            "properties": {
                              "decide": {
                                "type": "boolean",
                                "description": "Allows this key to approve, reject, or cancel Human Gates requests within its scope."
                              }
                            }
                          }
                        }
                      },
                      {
                        "type": "object",
                        "required": [
                          "scope",
                          "workspaceIds"
                        ],
                        "properties": {
                          "scope": {
                            "type": "string",
                            "enum": [
                              "workspace"
                            ]
                          },
                          "workspaceIds": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "minItems": 1
                          },
                          "approvals": {
                            "type": "object",
                            "properties": {
                              "decide": {
                                "type": "boolean",
                                "description": "Allows this key to approve, reject, or cancel Human Gates requests within its scope."
                              }
                            }
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "API key created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiKey": {
                      "$ref": "#/components/schemas/ApiKey"
                    },
                    "plainKey": {
                      "type": "string",
                      "description": "The full API key (only shown once)"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "API Keys"
        ],
        "summary": "List API keys",
        "operationId": "listApiKeys",
        "responses": {
          "200": {
            "description": "List of API keys",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apiKeys": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ApiKey"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/api-keys/{id}": {
      "delete": {
        "tags": [
          "API Keys"
        ],
        "summary": "Delete an API key",
        "operationId": "deleteApiKey",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "API key deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "API key not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers": {
      "post": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Reuse the MCP Workspace endpoint",
        "deprecated": true,
        "description": "Every MCP Workspace already has one endpoint. The legacy two-step flow may configure a newly prepared unused endpoint once and return 201. After configuration or authorization it returns the endpoint unchanged with 200, or 409 for differing explicit settings. Migrated endpoints are never implicitly reconfigured. Use updateMcpServer for intentional changes.",
        "operationId": "createMcpServer",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "workspaceId"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "description": {
                    "type": "string"
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "TOOLS",
                      "CODE"
                    ]
                  },
                  "settings": {
                    "$ref": "#/components/schemas/McpServerSettings"
                  },
                  "authMode": {
                    "type": "string",
                    "enum": [
                      "oauth",
                      "bearer",
                      "oauth_and_bearer"
                    ],
                    "description": "OAuth is the default. Bearer modes accept API-created end-user bearer tokens. A shared static bearer token is returned only when the workspace can safely use one or the server itself is scoped to one end user."
                  },
                  "endUserAccess": {
                    "type": "string",
                    "enum": [
                      "restricted",
                      "open"
                    ],
                    "description": "Controls whether MCP OAuth is limited to pre-added workspace end users or allows end users to join during sign-in."
                  },
                  "createdBy": {
                    "type": "string"
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The server will use this end user's connections."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Existing MCP Workspace endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "server",
                    "mcpEndpoint"
                  ],
                  "properties": {
                    "server": {
                      "$ref": "#/components/schemas/McpServer"
                    },
                    "mcpEndpoint": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "201": {
            "description": "Initial legacy configuration of an unused MCP Workspace endpoint",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "server",
                    "mcpEndpoint"
                  ],
                  "properties": {
                    "bearerToken": {
                      "type": "string",
                      "description": "Newly created static bearer secret, returned only once when the initial authentication configuration allows one."
                    },
                    "server": {
                      "$ref": "#/components/schemas/McpServer"
                    },
                    "mcpEndpoint": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "MCP server limit reached or workspace access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "End user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "MCP Workspace already configured; update its endpoint explicitly",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "List MCP servers",
        "operationId": "listMcpServers",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "includeSuspended",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of MCP servers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "servers",
                    "total"
                  ],
                  "properties": {
                    "servers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/McpServer"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "Workspace-scoped API keys list only resources in their allowed workspaces. Org-wide resources require an org-wide API key."
      }
    },
    "/api/v1/mcp/servers/{id}": {
      "get": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Get MCP server details with tools",
        "operationId": "getMcpServer",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MCP server with tools",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "server",
                    "tools"
                  ],
                  "properties": {
                    "server": {
                      "$ref": "#/components/schemas/McpServer"
                    },
                    "tools": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/McpServerTool"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "MCP server not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Update MCP server",
        "operationId": "updateMcpServer",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "allowWorkspaceMembers": {
                    "type": "boolean",
                    "description": "Explicitly allow authenticated organization members to authorize this endpoint. Does not share private app credentials."
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "TOOLS",
                      "CODE"
                    ]
                  },
                  "settings": {
                    "$ref": "#/components/schemas/McpServerSettings"
                  },
                  "authMode": {
                    "type": "string",
                    "enum": [
                      "oauth",
                      "bearer",
                      "oauth_and_bearer"
                    ],
                    "description": "Bearer-enabled modes accept API-created end-user bearer tokens. A shared static bearer token is created only when the workspace can safely use one or the server itself is scoped to one end user."
                  },
                  "endUserAccess": {
                    "type": "string",
                    "enum": [
                      "restricted",
                      "open"
                    ],
                    "description": "Controls whether MCP OAuth is limited to pre-added workspace end users or allows end users to join during sign-in."
                  },
                  "endUserId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The external ID of the end user (your application's user identifier). The server will use this end user's connections. Set to null to remove."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "MCP server updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "server"
                  ],
                  "properties": {
                    "mcpEndpoint": {
                      "type": "string",
                      "format": "uri"
                    },
                    "server": {
                      "$ref": "#/components/schemas/McpServer"
                    },
                    "bearerToken": {
                      "type": "string",
                      "description": "Static MCP bearer token. Returned only when switching to a bearer-enabled auth mode and no bearer token existed yet."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or workspace required for the requested auth/end-user setting",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "MCP server or end user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Delete an MCP server",
        "operationId": "deleteMcpServer",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "MCP server deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "MCP server not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Primary MCP Workspace endpoint cannot be deleted separately; delete its workspace explicitly",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers/{id}/regenerate-token": {
      "post": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Regenerate MCP server bearer token",
        "operationId": "regenerateMcpServerToken",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "New bearer token generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "bearerToken",
                    "mcpEndpoint"
                  ],
                  "properties": {
                    "bearerToken": {
                      "type": "string"
                    },
                    "mcpEndpoint": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "MCP server not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Static bearer auth is not enabled for this MCP server",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/workspaces/{id}/access-tokens": {
      "post": {
        "tags": [
          "Workspaces"
        ],
        "summary": "Create private MCP Workspace access",
        "operationId": "createWorkspaceAccessToken",
        "description": "Issues a private token and endpoint for one existing external end user in this MCP Workspace. Uses the endpoint's existing OAuth or bearer authentication without changing its settings. Keep this token private and provision it only to that user’s agent. API keys must have access to this workspace.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "endUserId"
                ],
                "properties": {
                  "endUserId": {
                    "type": "string",
                    "description": "Your application's external user ID. Internal Weavz user UUIDs are not accepted."
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional MCP scopes. Defaults to the scopes supported by the server mode."
                  },
                  "expiresIn": {
                    "type": "integer",
                    "minimum": 300,
                    "maximum": 7776000,
                    "description": "Token lifetime in seconds. Defaults to 30 days."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Private MCP Workspace token created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "accessToken",
                    "token",
                    "mcpEndpoint"
                  ],
                  "properties": {
                    "accessToken": {
                      "type": "string",
                      "description": "Token value. Send as Authorization: Bearer."
                    },
                    "bearerToken": {
                      "type": "string",
                      "description": "Same value as accessToken; present only for bearer-authenticated endpoints."
                    },
                    "token": {
                      "type": "object",
                      "required": [
                        "id",
                        "tokenPrefix",
                        "scopes",
                        "endUserId",
                        "authMethod",
                        "tokenType",
                        "expiresAt",
                        "createdAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "tokenPrefix": {
                          "type": "string"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "endUserId": {
                          "type": "string"
                        },
                        "authMethod": {
                          "type": "string",
                          "enum": [
                            "bearer",
                            "oauth"
                          ]
                        },
                        "tokenType": {
                          "type": "string",
                          "enum": [
                            "mcp_bearer",
                            "mcp_oauth"
                          ]
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "mcpEndpoint": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or workspace-scoped MCP server required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Workspace scope denied, suspended workspace or endpoint, or session cannot act for this user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "MCP Workspace or external end user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Endpoint authentication was changed during issuance; retry with its current settings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers/{id}/access-tokens": {
      "post": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Create an end-user scoped MCP bearer token",
        "operationId": "createMcpServerAccessToken",
        "description": "Issues an mcp_ bearer token scoped to one end user for programmatic MCP client provisioning. The MCP server must use bearer or OAuth + bearer auth.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "endUserId"
                ],
                "properties": {
                  "endUserId": {
                    "type": "string",
                    "description": "End user's external ID, or internal UUID when using dashboard-created end users."
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional MCP scopes. Defaults to the scopes supported by the server mode."
                  },
                  "expiresIn": {
                    "type": "integer",
                    "minimum": 300,
                    "maximum": 7776000,
                    "description": "Token lifetime in seconds. Defaults to 30 days."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "End-user MCP bearer token created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "accessToken",
                    "bearerToken",
                    "token",
                    "mcpEndpoint"
                  ],
                  "properties": {
                    "accessToken": {
                      "type": "string",
                      "description": "Token value. Send as Authorization: Bearer."
                    },
                    "bearerToken": {
                      "type": "string",
                      "description": "Same token value, named for bearer-token provisioning flows."
                    },
                    "token": {
                      "type": "object",
                      "required": [
                        "id",
                        "tokenPrefix",
                        "scopes",
                        "endUserId",
                        "authMethod",
                        "tokenType",
                        "expiresAt",
                        "createdAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "tokenPrefix": {
                          "type": "string"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "endUserId": {
                          "type": "string"
                        },
                        "authMethod": {
                          "type": "string",
                          "enum": [
                            "bearer"
                          ]
                        },
                        "tokenType": {
                          "type": "string",
                          "enum": [
                            "mcp_bearer"
                          ]
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "mcpEndpoint": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or workspace-scoped MCP server required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "MCP server or end user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "End-user bearer tokens are not enabled for this server",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers/{id}/oauth-tokens": {
      "post": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Create an end-user scoped MCP OAuth access token",
        "operationId": "createMcpServerOAuthToken",
        "description": "Issues an MCP access token scoped to one end user for programmatic MCP client provisioning.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "endUserId"
                ],
                "properties": {
                  "endUserId": {
                    "type": "string",
                    "description": "End user's external ID, or internal UUID when using dashboard-created end users."
                  },
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional MCP scopes. Defaults to the scopes supported by the server mode."
                  },
                  "expiresIn": {
                    "type": "integer",
                    "minimum": 300,
                    "maximum": 7776000,
                    "description": "Token lifetime in seconds. Defaults to 30 days."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "MCP OAuth access token created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "accessToken",
                    "token",
                    "mcpEndpoint"
                  ],
                  "properties": {
                    "accessToken": {
                      "type": "string"
                    },
                    "token": {
                      "type": "object",
                      "required": [
                        "id",
                        "tokenPrefix",
                        "scopes",
                        "endUserId",
                        "expiresAt",
                        "createdAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "tokenPrefix": {
                          "type": "string"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "endUserId": {
                          "type": "string"
                        },
                        "expiresAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "createdAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "mcpEndpoint": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or workspace-scoped MCP server required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "MCP server or end user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "MCP OAuth is not enabled for this server",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers/{id}/tools": {
      "post": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Add a tool to an MCP server",
        "operationId": "addMcpServerTool",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "integrationName",
                  "actionName"
                ],
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "actionName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "integrationAlias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$",
                    "description": "Optional server-local alias selector. Tool Mode names use this as the `{alias}__{action}` prefix. Prefer purpose-readable names such as `office_slack`; defaults to `integrationName` when omitted."
                  },
                  "toolType": {
                    "type": "string",
                    "enum": [
                      "ACTION"
                    ],
                    "default": "ACTION"
                  },
                  "connectionId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "displayName": {
                    "type": "string"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "inputDefaults": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "partialIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Partial IDs or names to assign to this tool. Partials must match the tool integration alias. If omitted, matching default partials can still apply."
                  },
                  "sortOrder": {
                    "type": "number",
                    "default": 0
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Tool added",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tool": {
                      "$ref": "#/components/schemas/McpServerTool"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "MCP server not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Tool already exists or alias conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers/{id}/tools/{toolId}": {
      "patch": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Update an MCP server tool",
        "operationId": "updateMcpServerTool",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "toolId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "displayName": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "inputDefaults": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "connectionId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  },
                  "sortOrder": {
                    "type": "number"
                  },
                  "integrationAlias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$"
                  },
                  "partialIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Partial IDs or names to assign to this tool. Partials must match the tool integration alias. Send an empty array to clear assigned partials; matching default partials can still apply."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tool updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "tool": {
                      "$ref": "#/components/schemas/McpServerTool"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "MCP server or tool not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Delete an MCP server tool",
        "operationId": "deleteMcpServerTool",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "toolId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tool deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "MCP server or tool not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers/{id}/execute-code": {
      "post": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Execute or resume Code Mode against an MCP server",
        "description": "Execute JavaScript against a Code Mode MCP server, or fetch the result of a previously approved Human Gate by passing the returned `approvalId`. Code Mode executions can run for up to 5 minutes. When a Code Mode run is gated, approve it first, then call this endpoint again with only `approvalId`; do not resend the original code.",
        "operationId": "executeMcpCode",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "x-source",
            "in": "header",
            "description": "Optional source identifier for usage attribution",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "oneOf": [
                  {
                    "required": [
                      "code"
                    ]
                  },
                  {
                    "required": [
                      "approvalId"
                    ]
                  }
                ],
                "properties": {
                  "code": {
                    "type": "string",
                    "minLength": 1,
                    "description": "JavaScript Code Mode source to execute."
                  },
                  "approvalId": {
                    "type": "string",
                    "pattern": "^apr_",
                    "description": "Approval request ID returned by an approval-required Code Mode result."
                  },
                  "waitForApprovalSeconds": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 60,
                    "description": "Optional seconds to keep an approvalId continuation call open while the Human Gate is still pending. Defaults to the MCP server Code Mode setting."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code execution result, approval-required continuation, pending approval status, or cached approved result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "content": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "structuredContent": {
                      "type": "object",
                      "description": "MCP structured content for Code Mode results. Executed runs include status, output, logs, action traces, and timing metadata; approval-required runs include approval links and continuation arguments.",
                      "additionalProperties": true
                    },
                    "isError": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Sandbox quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "MCP server not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/mcp/servers/{id}/declarations/{alias}": {
      "get": {
        "tags": [
          "MCP Servers"
        ],
        "summary": "Get TypeScript declarations for a code-mode alias",
        "description": "Returns generated TypeScript declarations for a specific alias on a code-mode MCP server. Declarations include concrete return types when an action has a declared return contract; broad third-party API passthrough actions may return unknown. Use this to give code-mode agents or editors a typed view of available alias tools.",
        "operationId": "getMcpDeclarations",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "alias",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Configured integration alias on this MCP server"
          }
        ],
        "responses": {
          "200": {
            "description": "TypeScript declarations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "declarations": {
                      "type": "string",
                      "description": "Generated TypeScript declaration (.d.ts) content"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "MCP server or integration not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "List available integrations or get a specific integration",
        "operationId": "listIntegrations",
        "security": [],
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "description": "Optional integration name to fetch specific integration metadata",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "summary",
            "in": "query",
            "description": "Return lightweight integration summaries instead of full action and trigger metadata.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of integrations or specific integration",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "integrations": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/IntegrationMetadata"
                          }
                        },
                        "total": {
                          "type": "integer"
                        },
                        "registered": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "integration": {
                          "$ref": "#/components/schemas/IntegrationMetadata"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Integration not found (when name query param is provided)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations/{integrationName}/properties/options": {
      "post": {
        "tags": [
          "Integrations"
        ],
        "summary": "Resolve dropdown property options",
        "operationId": "resolveIntegrationPropertyOptions",
        "parameters": [
          {
            "name": "integrationName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "propertyName"
                ],
                "properties": {
                  "actionName": {
                    "type": "string"
                  },
                  "triggerName": {
                    "type": "string"
                  },
                  "propertyName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "connectionExternalId": {
                    "type": "string"
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key to disambiguate direct credential resolution when an integration supports multiple auth methods."
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "workspaceIntegrationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Configured workspace integration instance to use for connection strategy resolution."
                  },
                  "integrationAlias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$",
                    "description": "Workspace integration alias to use when workspaceIntegrationId is not provided."
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The API resolves this to the internal end user record. Used for per-user connection resolution and for stateful workspace integrations, including browser profile reuse, when the targeted workspace integration's persistence policy is end_user."
                  },
                  "input": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "partialIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Partial IDs or names to apply before resolving options. If omitted, matching defaults apply. Send an empty array to resolve without defaults."
                  },
                  "searchValue": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Property options",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "options": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "disabled": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Integration, action, trigger, or property not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations/{integrationName}/properties/resolve": {
      "post": {
        "tags": [
          "Integrations"
        ],
        "summary": "Resolve dynamic property schema",
        "operationId": "resolveIntegrationProperty",
        "parameters": [
          {
            "name": "integrationName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "propertyName"
                ],
                "properties": {
                  "actionName": {
                    "type": "string"
                  },
                  "triggerName": {
                    "type": "string"
                  },
                  "propertyName": {
                    "type": "string",
                    "minLength": 1
                  },
                  "connectionExternalId": {
                    "type": "string"
                  },
                  "authMethodKey": {
                    "type": "string",
                    "description": "Auth method key to disambiguate direct credential resolution when an integration supports multiple auth methods."
                  },
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "workspaceIntegrationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Configured workspace integration instance to use for connection strategy resolution."
                  },
                  "integrationAlias": {
                    "type": "string",
                    "maxLength": 64,
                    "pattern": "^[a-z][a-z0-9_-]*$",
                    "description": "Workspace integration alias to use when workspaceIntegrationId is not provided."
                  },
                  "endUserId": {
                    "type": "string",
                    "description": "The external ID of the end user (your application's user identifier). The API resolves this to the internal end user record. Used for per-user connection resolution and for stateful workspace integrations, including browser profile reuse, when the targeted workspace integration's persistence policy is end_user."
                  },
                  "input": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "partialIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Partial IDs or names to apply before resolving the dynamic property. If omitted, matching defaults apply. Send an empty array to resolve without defaults."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resolved property schema",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Integration, action, trigger, or property not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/integrations/oauth-status": {
      "get": {
        "tags": [
          "Integrations"
        ],
        "summary": "Get OAuth configuration status for all integrations",
        "operationId": "getIntegrationsOAuthStatus",
        "responses": {
          "200": {
            "description": "List of integrations with configured OAuth",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "configured": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Integration names with OAuth apps configured"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/end-users": {
      "post": {
        "tags": [
          "End Users"
        ],
        "summary": "Create an end user",
        "description": "Creates a new end user within a workspace. The externalId must be unique within the workspace.",
        "operationId": "createEndUser",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "workspaceId",
                  "externalId"
                ],
                "properties": {
                  "workspaceId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Workspace to create the end user in"
                  },
                  "externalId": {
                    "type": "string",
                    "minLength": 1,
                    "description": "Your application's end-user identifier, stored as endUser.externalId within the workspace"
                  },
                  "displayName": {
                    "type": "string",
                    "description": "Human-readable display name"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "End user email address"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true,
                    "description": "Arbitrary metadata to attach"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "End user created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endUser": {
                      "$ref": "#/components/schemas/EndUser"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "End user with this externalId already exists in the workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": [
          "End Users"
        ],
        "summary": "List end users",
        "operationId": "listEndUsers",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "query",
            "required": true,
            "description": "Filter by workspace ID",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Match a literal substring of externalId, displayName, or email, ignoring case. Percent signs and underscores match themselves.",
            "schema": {
              "type": "string",
              "maxLength": 200
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of end users",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endUsers": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/EndUser"
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/end-users/{id}": {
      "get": {
        "tags": [
          "End Users"
        ],
        "summary": "Get end user by ID",
        "description": "Returns end user details including their connections.",
        "operationId": "getEndUser",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "End user details with connections",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endUser": {
                      "$ref": "#/components/schemas/EndUser"
                    },
                    "connections": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Connection"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "End user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "End Users"
        ],
        "summary": "Update an end user",
        "operationId": "updateEndUser",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "displayName": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "email": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "email"
                  },
                  "metadata": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "additionalProperties": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "End user updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endUser": {
                      "$ref": "#/components/schemas/EndUser"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No updates provided",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "End user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "End Users"
        ],
        "summary": "Delete an end user",
        "description": "Deletes the end user and cascades to their connections.",
        "operationId": "deleteEndUser",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "End user deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "deleted": {
                      "type": "boolean"
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "End user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "End user is the default identity of a primary MCP Workspace endpoint; explicitly change the binding before deleting",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/end-users/{id}/connect-token": {
      "post": {
        "tags": [
          "End Users"
        ],
        "summary": "Generate a connect portal URL for an end user",
        "description": "Creates a connect session token scoped to this end user. Returns a URL that can be\nopened in a popup or embedded to let the end user connect their own accounts.\n",
        "operationId": "createEndUserConnectToken",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "integrationName": {
                    "type": "string",
                    "description": "Optionally restrict to a base integration name. Use workspaceIntegrationId when selecting a configured workspace integration alias."
                  },
                  "workspaceIntegrationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optionally restrict to one configured workspace integration."
                  },
                  "expiresIn": {
                    "type": "integer",
                    "minimum": 3600,
                    "maximum": 2592000,
                    "description": "Token expiration in seconds, from 1 hour to 30 days. Defaults to 604800 (7 days)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Connect portal URL generated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connectUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "URL to open for the end user connect portal"
                    },
                    "token": {
                      "type": "string",
                      "description": "End-user connect portal token (eut_...)"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "End user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/end-users/{id}/invite": {
      "post": {
        "tags": [
          "End Users"
        ],
        "summary": "Send an email invitation to an end user",
        "description": "Sends an email to the end user with a link to connect their accounts.\nRequires email sending to be configured.\n",
        "operationId": "inviteEndUser",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Email address to send the invitation to"
                  },
                  "integrationName": {
                    "type": "string",
                    "description": "Optionally restrict to a base integration name. Use workspaceIntegrationId when selecting a configured workspace integration alias."
                  },
                  "workspaceIntegrationId": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Optionally restrict to one configured workspace integration."
                  },
                  "expiresIn": {
                    "type": "integer",
                    "minimum": 3600,
                    "maximum": 2592000,
                    "description": "Invitation link expiration in seconds, from 1 hour to 30 days. Defaults to 604800 (7 days)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Invitation link created and email delivery attempted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "connectUrl",
                    "token",
                    "expiresAt",
                    "emailSent"
                  ],
                  "properties": {
                    "connectUrl": {
                      "type": "string",
                      "format": "uri",
                      "description": "Hosted connect portal URL for the end user"
                    },
                    "token": {
                      "type": "string",
                      "description": "End-user connect portal token (eut_...)"
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "emailSent": {
                      "type": "boolean",
                      "description": "Whether the invite email was accepted by the configured email provider"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "End user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/computer-sessions/{id}/access": {
      "post": {
        "tags": [
          "Computer Sessions"
        ],
        "summary": "Create human computer-session access",
        "description": "Issue a short-lived link for a human to watch or control a computer session from your trusted application backend. This endpoint does not grant agent tool control.",
        "operationId": "createComputerSessionAccess",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ComputerSessionAccessInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Short-lived human viewer access",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "description": "Always no-store."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComputerSessionAccess"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request, origin, or missing workspace and external end-user scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Computer session or matching end user not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Computer session is stopped or expired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or active embedding-origin limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Computer session access is temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/skills": {
      "get": {
        "tags": [
          "Skills"
        ],
        "summary": "List or search skill metadata",
        "description": "Search names, slugs, descriptions and tags in one authorized library. Markdown is never included. Skills do not run actions or grant app access. Personal scope requires the customer's external endUserId.",
        "operationId": "listSkills",
        "parameters": [
          {
            "$ref": "#/components/parameters/SkillWorkspace"
          },
          {
            "$ref": "#/components/parameters/SkillScope"
          },
          {
            "$ref": "#/components/parameters/SkillEndUser"
          },
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 120
            }
          },
          {
            "name": "tag",
            "in": "query",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 32
            }
          },
          {
            "name": "includeDisabled",
            "in": "query",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 25
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Skill metadata and pagination",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillListResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or missing external end-user identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Skill or end user not found in this library",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion or duplicate library slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or fixed technical library limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Skill storage temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Skills"
        ],
        "summary": "Create a skill",
        "description": "Save optional reusable instructions. Defaults to the specified end user's personal library. Scope and owner are immutable after creation; copy the content to create a shared skill. Technical limits apply equally on every plan.",
        "operationId": "createSkill",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSkillInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Skill created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or missing external end-user identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Skill or end user not found in this library",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion or duplicate library slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or fixed technical library limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Skill storage temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/skills/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "tags": [
          "Skills"
        ],
        "summary": "Explicitly read a skill",
        "description": "Read user-authored Markdown from the selected authorized library. Reading does not execute the instructions or change app permissions.",
        "operationId": "readSkill",
        "parameters": [
          {
            "$ref": "#/components/parameters/SkillWorkspace"
          },
          {
            "$ref": "#/components/parameters/SkillScope"
          },
          {
            "$ref": "#/components/parameters/SkillEndUser"
          }
        ],
        "responses": {
          "200": {
            "description": "Skill instructions and current version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or missing external end-user identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Skill or end user not found in this library",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion or duplicate library slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or fixed technical library limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Skill storage temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Skills"
        ],
        "summary": "Update a skill at its current version",
        "description": "Atomically update content only when expectedVersion matches. A concurrent edit returns 409 and leaves the newer content unchanged.",
        "operationId": "updateSkill",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateSkillInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Skill updated with an incremented version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SkillResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or missing external end-user identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Skill or end user not found in this library",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion or duplicate library slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or fixed technical library limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Skill storage temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Skills"
        ],
        "summary": "Delete a skill at its current version",
        "description": "Remove stored instructions only. Does not disconnect apps or revoke permissions. A concurrent change returns 409 instead of deleting the newer version.",
        "operationId": "deleteSkill",
        "parameters": [
          {
            "$ref": "#/components/parameters/SkillWorkspace"
          },
          {
            "$ref": "#/components/parameters/SkillScope"
          },
          {
            "$ref": "#/components/parameters/SkillEndUser"
          },
          {
            "name": "expectedVersion",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Skill deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "deleted",
                    "id"
                  ],
                  "properties": {
                    "deleted": {
                      "type": "boolean",
                      "const": true
                    },
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or missing external end-user identity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "API key cannot access this workspace",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Skill or end user not found in this library",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stale expectedVersion or duplicate library slug",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or fixed technical library limit reached",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Skill storage temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  }
}
