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

# Create session

> Creates a voice session for the logged-in user and returns a `participant_token`. **Requires a bearer login session** — an API key alone returns `400`. Scope `sessions:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /sessions
openapi: 3.1.0
info:
  title: Lehar API
  version: v0
  description: >-
    Customer-facing REST API for the Lehar voice-AI platform. Platform-admin
    endpoints are intentionally excluded from this reference. Regenerate with
    `npm run sync:openapi`.
servers:
  - url: https://api.lehar.ai/ca/api/v0
security:
  - ApiKeyAuth: []
  - BearerAuth: []
paths:
  /sessions:
    post:
      tags:
        - Sessions
      summary: Create session
      description: >-
        Creates a voice session for the logged-in user and returns a
        `participant_token`. **Requires a bearer login session** — an API key
        alone returns `400`. Scope `sessions:write`.
      operationId: create_customer_session_ca_api_v0_sessions_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_id
              properties:
                agent_id:
                  type: string
                  description: Agent to run.
                call_type:
                  type: string
                  enum:
                    - web
                    - outbound_phone
                  default: web
                phone_number:
                  type: string
                  description: E.164 number to dial for `outbound_phone`.
                participant_identity:
                  type: string
                  description: Defaults to the auth user id.
                participant_name:
                  type: string
                  description: Defaults to the logged-in user's name.
                custom_variables:
                  type: object
                  description: Values substituted into the agent's prompt.
                config:
                  type: object
                  description: Per-session provider overrides.
                metadata:
                  type: object
                  description: Client metadata (trusted ids are server-stamped).
            example:
              agent_id: agent_sales_hi
              custom_variables:
                callee_name: Jane
                company: Acme
              config:
                tts_provider: sarvam
                voice: anushka
      responses:
        '201':
          description: >-
            Created session with participant token (the only place the token is
            returned)
          content:
            application/json:
              example:
                session_id: session_01EXAMPLE
                customer_id: customer_01EXAMPLE
                user_id: user_01EXAMPLE
                user_name: Jane Operator
                agent_id: agent_sales_hi
                agent_name: Sales Agent
                livekit_url: wss://media.lehar.ai
                room_name: room_01EXAMPLE
                participant_identity: user_01EXAMPLE
                participant_name: Jane Operator
                participant_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                dispatch_id: disp_01EXAMPLE
                metadata:
                  customer_id: customer_01EXAMPLE
                  user_id: user_01EXAMPLE
                  agent_id: agent_sales_hi
                  session_id: session_01EXAMPLE
                status: active
                started_at: '2026-05-22T10:00:00Z'
                ended_at: null
                call_type: web
        '400':
          description: Bearer login required (an API key alone is rejected)
          content:
            application/json:
              example:
                error:
                  code: invalid_request
                  message: Bearer login is required to create sessions
      security:
        - BearerAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
    BearerAuth:
      type: http
      scheme: bearer

````