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

# Create Session

> Opens a new chat session for a customer with the specified agent. Any existing active session for the same customer + agent is closed first, so there is at most one active session per customer per agent.

Returns the full session object, including its `id` — use that `id` for the support and inject-context endpoints. Sending messages, however, does not require the session id: the [Send Message](/api-reference/endpoint/chat/send_message) endpoint resolves the active session automatically.



## OpenAPI

````yaml POST /v1/chat/session
openapi: 3.1.0
info:
  title: OSVI AI API
  description: REST API for the OSVI AI voice and chat platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.osvi.ai
security:
  - ApiToken: []
paths:
  /v1/chat/session:
    post:
      summary: Create a chat session
      description: >-
        Opens a new chat session for a customer with the specified agent. Any
        existing active session for the same customer + agent is closed first,
        so there is at most one active session per customer per agent.


        Returns the full session object, including its `id` — use that `id` for
        the support and inject-context endpoints. Sending messages, however,
        does not require the session id: the [Send
        Message](/api-reference/endpoint/chat/send_message) endpoint resolves
        the active session automatically.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - agent_uuid
                - customer_id
              properties:
                agent_uuid:
                  type: string
                  description: >-
                    Unique identifier of the OSVI agent to chat with. Must be an
                    active, non-archived agent belonging to the account that
                    owns the API token.
                  example: agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og
                customer_id:
                  type: string
                  description: >-
                    Your identifier for the customer on the other side of the
                    conversation — typically a phone number, but any stable
                    string works. Used to resolve the active session on
                    subsequent messages.
                  example: '+15551112222'
                input_fields:
                  type: object
                  additionalProperties: true
                  description: >-
                    Arbitrary key-value object describing the customer, made
                    available to the agent at runtime (e.g. name, account tier).
                  example:
                    first_name: Alex
                context:
                  type: array
                  items:
                    type: string
                  description: >-
                    Initial free-text context entries for the session. Only the
                    most recent 5 non-empty strings are retained (FIFO). Append
                    more later with the inject-context endpoint.
                  example:
                    - Initial context for this chat
      responses:
        '201':
          description: Session created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/ChatV1Session'
        '400':
          description: A required parameter (`agent_uuid` or `customer_id`) is missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '401':
          description: Invalid or missing API token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '404':
          description: >-
            The agent does not exist or is not associated with the authenticated
            account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
        '422':
          description: >-
            The agent is archived (`agent_archived`) or not active
            (`agent_inactive`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatV1Error'
components:
  schemas:
    ChatV1Session:
      type: object
      description: A chat session record.
      properties:
        id:
          type: string
          description: Session UUID. Use this for the support and inject-context endpoints.
          example: 4718a326-417b-4dda-90d0-21fd65a11cb8
        chat_agent_id:
          type: integer
          description: Internal numeric id of the agent handling the session.
          example: 42
        account_id:
          type: integer
          description: Id of the account that owns the session.
          example: 7
        customer_id:
          type: string
          description: Your identifier for the customer.
          example: '+15551112222'
        mode:
          type: string
          enum:
            - ai
            - support
          description: >-
            `ai` while the agent is responding, `support` when a human operator
            has taken over.
          example: ai
        help_requested:
          type: boolean
          description: Whether the agent has escalated for a human operator.
          example: false
        status:
          type: string
          enum:
            - active
            - closed
          example: active
        current_state:
          type: string
          nullable: true
          description: >-
            Current state name for multi-prompt agents. `null` for single-prompt
            agents.
          example: null
        metadata:
          type: object
          description: Bucketed session metadata.
          properties:
            input_fields:
              type: object
              additionalProperties: true
              description: Customer data supplied at session creation.
              example:
                first_name: Alex
            state_fields:
              type: object
              additionalProperties: true
              description: Mutable fields the agent maintains during the conversation.
              example: {}
            context:
              type: array
              items:
                type: string
              description: Free-text context entries (FIFO-capped).
              example:
                - Initial context for this chat
        active_human:
          type: string
          nullable: true
          description: >-
            Email of the operator currently holding the session, or `null` if
            the agent is in control.
          example: null
        created_at:
          type: string
          format: date-time
          example: '2026-06-04T11:40:25.690486Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-06-04T11:40:25.690486Z'
    ChatV1Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          description: Machine-readable error code or message.
          example: agent_not_found
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: API-Token
      description: >-
        16-character API token associated with your OSVI account. Find it in
        your dashboard under Settings → API.

````