> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Open a WebSocket on a `when.ws` trigger > WebSocket upgrade. The credential comes from the Authorization header (Bearer), the token sub-protocol `openai-insecure-api-key.` (browsers, which cannot set the header; `realtime` is accepted alongside it) or the access-token cookie, never from the query string. The cookie only counts from a page the api-gateway CORS rule allows. The native module named by the trigger handles the connection. A runtime replica that is full, a workspace past its share of the connections, or a module turned off accept the connection, send an `error` event (code `too_many_connections`, `workspace_share_reached` or `module_disabled`) and close it with `1013` (Try Again Later): a browser never sees the HTTP status of a refused upgrade. ## OpenAPI ````yaml /api-reference/swagger.yml get /v2/workspaces/{workspaceId}/ws/{automationPath}* openapi: 3.0.0 info: version: 1.0.0 title: Prisme.ai APIs description: > Prisme.ai APIs specifications **Active organization.** Requests run in the context of one organization of the caller. It is chosen, by priority: the organization in the path (`/v2/orgs/{orgSlug}/...`), the organization of an organization API key, the `x-prismeai-org-slug` request header, then the caller's default organization. Send `x-prismeai-org-slug` with every request to pick the organization explicitly: the API answers 403 unless the caller is a member of that organization and it is active (platform admins may target any existing organization, suspended ones included). Responses echo the resolved organization in `x-prismeai-org-slug`. termsOfService: https://www.prisme.ai/mentions-legales contact: name: Prisme.ai Support Team email: support@prisme.ai url: https://www.prisme.ai license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.studio.prisme.ai description: Prisme.ai Cloud - url: https://{customDomain} description: Self-hosted Prisme.ai instance variables: customDomain: default: api.your-prisme-instance.com description: API hostname of your self-hosted Prisme.ai deployment - url: http://localhost:3001 description: Local development security: - BearerAuth: [] - OrgApiKeyAuth: [] - BearerAuth: [] OrgApiKeyAuth: [] tags: - name: API Gateway description: >- Authentication, session management, SSO providers, and user profile endpoints. - name: Prisme.ai Workspaces description: >- CRUD operations for workspaces and their resources (pages, apps, automations, imports, variables). - name: Prisme.ai Runtime description: Execute workspace automations and manage their runtime lifecycle. - name: Prisme.ai Events description: Event ingestion, delivery, and subscription filtering across the platform. - name: Organizations description: >- Manage organizations, members, roles, invites, groups, and org-level service accounts. - name: Subscriptions description: >- Manage organization subscription plans and tier assignments (SuperAdmin only). - name: Secrets description: Read and patch encrypted key-value secrets scoped to a workspace. - name: ApiKeys description: Create, list, rotate, and validate workspace-scoped API keys. - name: Permissions description: >- Share or unshare resources (workspaces, pages, …) with users via roles or fine-grained rules. - name: Monitoring description: Platform readiness checks across services (SuperAdmin only). - name: AuthProviders - name: OIDC description: >- Endpoints of the embedded OpenID Connect provider, mounted under /oidc. The protocol endpoints follow OpenID Connect Core / OAuth 2.0 and are best resolved from GET /oidc/.well-known/openid-configuration; the /oidc/interaction/* routes are Prisme.ai-specific and covered by no standard. paths: /v2/workspaces/{workspaceId}/ws/{automationPath}*: get: tags: - Prisme.ai Runtime summary: Open a WebSocket on a `when.ws` trigger description: >- WebSocket upgrade. The credential comes from the Authorization header (Bearer), the token sub-protocol `openai-insecure-api-key.` (browsers, which cannot set the header; `realtime` is accepted alongside it) or the access-token cookie, never from the query string. The cookie only counts from a page the api-gateway CORS rule allows. The native module named by the trigger handles the connection. A runtime replica that is full, a workspace past its share of the connections, or a module turned off accept the connection, send an `error` event (code `too_many_connections`, `workspace_share_reached` or `module_disabled`) and close it with `1013` (Try Again Later): a browser never sees the HTTP status of a refused upgrade. operationId: openWorkspaceWebsocket parameters: - name: workspaceId in: path required: true schema: type: string - name: automationPath in: path required: true description: >- The path declared in when.ws.path, with its parameters (e.g. v1/agents/agent_x). Can contain slashes. schema: type: string - name: org in: query description: >- Active organization of the connection: its governance applies, and it pays schema: type: string maxLength: 128 - name: language in: query description: 'voice module: ISO-639-1 language of the user speech' schema: type: string maxLength: 16 - name: context in: query description: >- voice module: conversation to resume (contextId), a new one otherwise schema: type: string maxLength: 128 - name: rate in: query description: >- voice module: speech rate of the answers, a multiplier of the voice's own (0.5 to 2) schema: type: string maxLength: 8 responses: '101': description: >- Switching protocols (also for a connection turned away with 1013, see above) '400': description: Invalid org parameter, path parameter or context '401': description: Unauthorized '403': description: >- Forbidden (a cookie from a page the CORS rule does not allow, or an organization the user is not a member of) '404': description: No such trigger components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT OrgApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.