openapi: 3.0.3
info:
  title: VideoSDK Real-Time Communication HLS Streaming Sessions API
  description: 'REST API for managing rooms, sessions, recordings, RTMP live streams, and HLS streaming for real-time audio and video communication applications. Requires a JWT token signed with your VideoSDK API key and secret, passed in the Authorization header (without a Bearer prefix).

    '
  version: '2.0'
  contact:
    name: VideoSDK Support
    email: support@videosdk.live
    url: https://www.videosdk.live/support
  termsOfService: https://www.videosdk.live/terms
  license:
    name: Proprietary
    url: https://www.videosdk.live/terms
servers:
- url: https://api.videosdk.live/v2
  description: VideoSDK v2 API
security:
- JWTAuth: []
tags:
- name: Sessions
  description: Manage and query meeting sessions and participants.
paths:
  /sessions:
    get:
      operationId: fetchSessions
      summary: Fetch Sessions
      description: Retrieve a paginated list of sessions for a given room.
      tags:
      - Sessions
      parameters:
      - name: roomId
        in: query
        required: true
        schema:
          type: string
        description: The ID of the Room.
      - name: customRoomId
        in: query
        schema:
          type: string
        description: Custom room ID specified during creation.
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: perPage
        in: query
        schema:
          type: integer
          default: 20
      responses:
        '200':
          description: Paginated list of sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionsResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{sessionId}:
    get:
      operationId: fetchSession
      summary: Fetch a Session
      description: Retrieve details of a specific session by its ID.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '404':
          description: Session not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{sessionId}/participants:
    get:
      operationId: fetchParticipants
      summary: Fetch Participants
      description: Retrieve all participants in a session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of participants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Participant'
        '404':
          description: Session not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /sessions/{sessionId}/participants/active:
    get:
      operationId: fetchActiveParticipants
      summary: Fetch Active Participants
      description: Retrieve participants currently active in a session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of active participants.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Participant'
  /sessions/{sessionId}/stats:
    get:
      operationId: fetchSessionStats
      summary: Fetch Session Quality Stats
      description: Retrieve quality statistics for a session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Session quality statistics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                  stats:
                    type: object
                    additionalProperties: true
  /sessions/{sessionId}/participant/{participantId}/stats:
    get:
      operationId: fetchParticipantStats
      summary: Fetch Peer Quality Stats
      description: Retrieve quality statistics for a specific participant in a session.
      tags:
      - Sessions
      parameters:
      - name: sessionId
        in: path
        required: true
        schema:
          type: string
      - name: participantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Participant quality statistics.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
components:
  schemas:
    PageInfo:
      type: object
      properties:
        currentPage:
          type: integer
        perPage:
          type: integer
        lastPage:
          type: integer
        total:
          type: integer
    Participant:
      type: object
      properties:
        participantId:
          type: string
        name:
          type: string
        timelog:
          type: array
          items:
            type: object
            properties:
              start:
                type: string
                format: date-time
              end:
                type: string
                format: date-time
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
    SessionsResponse:
      type: object
      properties:
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Session'
    Session:
      type: object
      properties:
        id:
          type: string
          description: Session document ID.
        roomId:
          type: string
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
        status:
          type: string
        links:
          type: object
          properties:
            get_room:
              type: string
              format: uri
            get_session:
              type: string
              format: uri
  securitySchemes:
    JWTAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'JWT token generated using your VideoSDK API key and secret (HS256). Pass the token directly without a "Bearer" prefix.

        '
externalDocs:
  description: VideoSDK API Reference
  url: https://docs.videosdk.live/api-reference/realtime-communication/intro