> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkarta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create WebSocket session

> Create a WebSocket session for a voice agent.

The connection URL is single-use and expires after 300 seconds by default. Keep it private.

See the [WebSocket guide](https://docs.getkarta.ai/guides/realtime.md) to connect.


## OpenAPI

````yaml openapi.json POST /websocket/sessions
openapi: 3.1.0
info:
  title: Karta Public API
  version: 1.0.0-draft
  description: >-
    Karta API reference for accounts, agents, calls, campaigns, WebSocket
    sessions, and billing.
servers:
  - url: https://api.getkarta.ai/public/v1
    description: Production
security:
  - BearerApiKey: []
tags:
  - name: Account
  - name: Agents
  - name: Calls
  - name: Phone numbers
  - name: Campaigns
  - name: Realtime
  - name: Billing
  - name: Webhooks
    description: Outgoing call events delivered to your server.
paths:
  /websocket/sessions:
    post:
      tags:
        - Realtime
      summary: Create WebSocket session
      description: Create a WebSocket session for a voice agent.
      operationId: createWebSocketSession
      parameters:
        - name: X-Request-ID
          in: header
          required: false
          description: Optional request-tracing identifier.
          schema:
            type: string
          example: example-request-001
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionRequest'
            example:
              agent_id: agentexample
              llm_dynamic_variables:
                customer_name: Alex
      responses:
        '201':
          description: Session created.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
            Cache-Control:
              schema:
                type: string
                enum:
                  - no-store
              description: Do not cache session credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
              example:
                signed_url: wss://voice.example.invalid/ws/?token=EXAMPLE_SINGLE_USE_TOKEN
        '400':
          description: Invalid request or account configuration.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AuthProblem'
                    title: Authentication or account configuration error
                  - $ref: '#/components/schemas/RequestProcessingError'
                    title: Request processing error
              examples:
                configuration:
                  summary: Account configuration error
                  value:
                    type: https://httpstatus.es/400
                    title: Missing Data Residency
                    status: 400
                    detail: Client dataResidency not set. Please contact support.
                    instance: example-request-001
                    code: missing_data_residency
                request:
                  summary: Request parsing error (illustrative message)
                  value:
                    message: Unexpected end of JSON input
        '401':
          description: Authentication failed.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProblem'
                title: Authentication or account configuration error
              examples:
                authentication:
                  summary: Missing API key
                  value:
                    type: https://httpstatus.es/401
                    title: Invalid API Key
                    status: 401
                    detail: API key is required
                    instance: example-request-001
                    code: invalid_api_key
        '403':
          description: API key not permitted for this operation.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthProblem'
                title: Authentication or account configuration error
              examples:
                authentication:
                  summary: Wrong key type
                  value:
                    type: https://httpstatus.es/403
                    title: Wrong API Key Type
                    status: 403
                    detail: Widget API keys may only be used on /widget paths
                    instance: example-request-001
                    code: wrong_key_audience
        '404':
          description: Live voice agent not found for this account.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SessionProblem'
                title: WebSocket session error
              example:
                type: urn:karta:problem:voice_agent_not_found
                title: Not Found
                status: 404
                detail: Voice agent not found.
                instance: urn:karta:request:example-request-001
                traceId: example-request-001
                code: voice_agent_not_found
        '422':
          description: Invalid agent_id or dynamic variables.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SessionProblem'
                title: WebSocket session error
              example:
                type: urn:karta:problem:validation_error
                title: Unprocessable Entity
                status: 422
                detail: One or more fields failed validation.
                instance: urn:karta:request:example-request-001
                traceId: example-request-001
                code: validation_error
                errors:
                  - path: agent_id
                    message: must be a non-empty string
        '500':
          description: Internal server error.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AuthProblem'
                    title: Authentication or account configuration error
                  - $ref: '#/components/schemas/RequestProcessingError'
                    title: Request processing error
              examples:
                authentication:
                  summary: Authentication failure
                  value:
                    type: https://httpstatus.es/500
                    title: Internal Server Error
                    status: 500
                    detail: Authentication failed
                    instance: example-request-001
                    code: internal_error
                request:
                  summary: Request processing failure
                  value:
                    message: Internal Server Error
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SessionProblem'
                title: WebSocket session error
              example:
                type: urn:karta:problem:internal_error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred.
                instance: urn:karta:request:example-request-001
                traceId: example-request-001
                code: internal_error
        '503':
          description: Session authentication is temporarily unavailable.
          headers:
            X-Request-ID:
              description: Request identifier.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/SessionProblem'
                title: WebSocket session error
              example:
                type: urn:karta:problem:websocket_authentication_unavailable
                title: Service Unavailable
                status: 503
                detail: WebSocket authentication is temporarily unavailable.
                instance: urn:karta:request:example-request-001
                traceId: example-request-001
                code: websocket_authentication_unavailable
components:
  schemas:
    SessionRequest:
      type: object
      properties:
        agent_id:
          type: string
          description: Live voice agent ID returned by List agents.
          minLength: 1
        llm_dynamic_variables:
          type:
            - object
            - 'null'
          properties: {}
          description: Prompt variables for this session; defaults to an empty object.
          additionalProperties: true
        agent_override:
          type: object
          properties:
            language_config:
              type: object
              properties:
                primary_language:
                  type: string
                  description: Non-empty language value supported by the configured agent.
                  minLength: 1
              required:
                - primary_language
              additionalProperties: false
          required:
            - language_config
          additionalProperties: false
          description: Invalid overrides are ignored and reported in warnings.
      required:
        - agent_id
    Session:
      type: object
      properties:
        signed_url:
          type: string
          description: Single-use WebSocket connection URL.
          format: uri
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                enum:
                  - agent_override_ignored
              path:
                type: string
              message:
                type: string
    AuthProblem:
      type: object
      properties:
        type:
          type: string
          description: Identifier for this error category.
        title:
          type: string
          description: Short summary of the error.
        status:
          type: integer
          description: HTTP status code for this response.
        detail:
          type: string
          description: Explanation of the failure.
        instance:
          type: string
          description: Request identifier.
        code:
          type: string
          description: Machine-readable error code.
      title: Authentication or account configuration error
    RequestProcessingError:
      title: Request processing error
      type: object
      properties:
        message:
          type: string
          description: Description of the request-processing failure.
        errors:
          type: array
          items:
            additionalProperties: true
            type: object
          description: Additional error details, when supplied.
    SessionProblem:
      type: object
      properties:
        type:
          type: string
          description: Identifier for this error category.
        title:
          type: string
          description: Short summary of the error.
        status:
          type: integer
          description: HTTP status code for this response.
        detail:
          type: string
          description: Explanation of the failure.
        instance:
          type: string
          description: Request identifier.
        code:
          type: string
          description: Machine-readable error code.
        traceId:
          type: string
          description: Request identifier for support and troubleshooting.
        errors:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              message:
                type: string
      title: WebSocket session error
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      description: 'API key in the format: Bearer YOUR_KARTA_API_KEY.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.