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

# Start Vision Session

> Attach Hawkeye-1 to a LiveKit room and begin real-time video analysis. Hawkeye joins as a subscriber, analyses the target participant's video, and streams alerts to your callback URL whenever a chosen class is detected. Billed at 1¢/minute. Requires `x-api-key` authentication.



## OpenAPI

````yaml POST /v2/vision
openapi: 3.0.3
info:
  title: TruGen Developer Platform API
  version: 1.0.0
  description: OpenAPI specification for MCP endpoint
servers:
  - url: https://api.trugen.ai/v1
security: []
paths:
  /v2/vision:
    servers:
      - url: https://api.trugen.ai
    post:
      summary: Start Vision Session
      description: >-
        Attach Hawkeye-1 to a LiveKit room and begin real-time video analysis.
        Hawkeye joins as a subscriber, analyses the target participant's video,
        and streams alerts to your callback URL whenever a chosen class is
        detected. Billed at 1¢/minute. Requires `x-api-key` authentication.
      operationId: startVisionSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - livekit_url
                - access_token
                - max_duration
              properties:
                livekit_url:
                  type: string
                  description: '`wss://` URL of the LiveKit room Hawkeye should join.'
                  example: wss://your-livekit-domain.livekit.cloud
                access_token:
                  type: string
                  description: 'LiveKit access token with `roomJoin: true` for that room.'
                  example: eyJhbGciOi...
                participant:
                  type: string
                  description: >-
                    Participant identity to analyse. Defaults to `"auto"` (first
                    non-agent participant).
                  example: auto
                callback_url:
                  type: string
                  description: WebSocket URL to receive real-time class-detection alerts.
                  example: wss://your-callback-endpoint.example.com/vision
                max_duration:
                  type: integer
                  description: Session cap in minutes. Hawkeye disconnects when reached.
                  example: 10
                modules:
                  type: object
                  description: >-
                    Modules to enable. Each key is a module name; each value is
                    the list of classes to alert on. Pass an empty array to
                    enable a module with all its default classes. Omit `modules`
                    entirely for all defaults.
                  additionalProperties:
                    type: array
                    items:
                      type: string
                  example:
                    face_pose_detection:
                      - Looking Left
                      - Looking Right
                    emotion_recognition:
                      - angry
                      - sad
                      - happy
                    eyegaze_tracking:
                      - Looking left
                      - Looking right
                    face_count:
                      - '2'
                    face_out_of_focus:
                      - out_of_frame
      responses:
        '200':
          description: Vision session accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  session_id:
                    type: string
                    format: uuid
                    example: 8f2a1e5b-4c9d-4a3f-9c11-2c07be7d1c22
                  status:
                    type: string
                    example: IN_QUEUE
                  max_duration:
                    type: integer
                    example: 10
                  modules:
                    type: array
                    items:
                      type: string
                    example:
                      - emotion_recognition
                      - eyegaze_tracking
                      - face_count
                      - face_out_of_focus
                      - face_pose_detection
        '400':
          description: >-
            Missing / invalid field (e.g. `livekit_url`, `access_token`, unknown
            module or class name).
        '401':
          description: Missing or invalid `x-api-key`.
        '502':
          description: >-
            Hawkeye backend rejected the request. Retry with fresh LiveKit
            credentials.
      security:
        - apiKeyAuth: []
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````