mirotalk/app/api/swagger.yaml

swagger: '2.0'

info:
    title: MiroTalk P2P API
    description: API description for external applications that integrates with MiroTalk P2P.
    version: 1.0.1

basePath: /api/v1

schemes:
    - https
    - http

paths:
    /stats:
        get:
            tags:
                - 'stats'
            summary: 'Get stats'
            description: 'Get stats'
            produces:
                - 'application/json'
            security:
                - secretApiKey: []
            responses:
                '200':
                    description: 'Get Stats done'
                    schema:
                        $ref: '#/definitions/StatsResponse'
                '403':
                    description: 'Unauthorized!'
    /meetings:
        get:
            tags:
                - 'meetings'
            summary: 'Get meetings'
            description: 'Get meetings'
            produces:
                - 'application/json'
            security:
                - secretApiKey: []
            responses:
                '200':
                    description: 'Get Meetings done'
                    schema:
                        $ref: '#/definitions/MeetingsResponse'
                '403':
                    description: 'Unauthorized!'
    /meeting:
        post:
            tags:
                - 'meeting'
            summary: 'Create meeting'
            description: 'Create meeting'
            consumes:
                - 'application/json'
            produces:
                - 'application/json'
            security:
                - secretApiKey: []
            responses:
                '200':
                    description: 'Meeting created'
                    schema:
                        $ref: '#/definitions/MeetingResponse'
                '403':
                    description: 'Unauthorized!'
    /join:
        post:
            tags:
                - 'join'
            summary: 'Create direct join'
            description: 'Create join'
            parameters:
                - in: body
                  name: Join
                  description: Custom Join URL.
                  schema:
                      type: object
                      properties:
                          room:
                              type: string
                              default: 'test'
                          name:
                              type: string
                              default: 'mirotalk'
                          avatar:
                              type: ['boolean', 'string'] # Allow boolean or string type
                              default: false
                          audio:
                              type: boolean
                              default: false
                          video:
                              type: boolean
                              default: false
                          screen:
                              type: boolean
                              default: false
                          chat:
                              type: boolean
                              default: false
                          hide:
                              type: boolean
                              default: false
                          notify:
                              type: boolean
                              default: false
                          duration:
                              type: string
                              default: 'unlimited'
                          token:
                              type: object
                              description: |
                                  Object containing authentication token details.
                                  This token is required when HOST_PROTECTED or HOST_USER_AUTH is enabled in the .env file.
                                  It includes properties such as username, password, presenter, and expire.
                              properties:
                                  username:
                                      type: string
                                      default: 'username'
                                  password:
                                      type: string
                                      default: 'password'
                                  presenter:
                                      type: boolean
                                      default: true
                                  expire:
                                      type: string
                                      default: '1h'
            consumes:
                - 'application/json'
            produces:
                - 'application/json'
            security:
                - secretApiKey: []
            responses:
                '200':
                    description: 'Direct join created'
                    schema:
                        $ref: '#/definitions/JoinResponse'
                '403':
                    description: 'Unauthorized!'

    /token:
        post:
            tags:
                - 'token'
            summary: 'Get token'
            description: 'Get token'
            parameters:
                - in: body
                  name: token
                  description: Custom Token.
                  schema:
                      $ref: '#/definitions/TokenRequest'
            consumes:
                - 'application/json'
            produces:
                - 'application/json'
            security:
                - secretApiKey: []
            responses:
                '200':
                    description: 'Get token done'
                    schema:
                        $ref: '#/definitions/TokenResponse'
                '403':
                    description: 'Unauthorized!'

securityDefinitions:
    secretApiKey:
        type: 'apiKey'
        name: 'authorization'
        in: 'header'
        description: 'Format like this: authorization: {API_KEY_SECRET}'

definitions:
    StatsResponse:
        type: object
        properties:
            success:
                type: boolean
            timestamp:
                type: string
                format: date-time
                example: '2025-12-21T12:00:00Z'
            totalRooms:
                type: integer
            totalPeers:
                type: integer

    MeetingsResponse:
        type: object
        properties:
            meetings:
                type: array
                items:
                    $ref: '#/definitions/Meeting'
    MeetingResponse:
        type: 'object'
        properties:
            meeting:
                type: 'string'
    JoinResponse:
        type: 'object'
        properties:
            join:
                type: 'string'
    TokenRequest:
        type: object
        properties:
            username:
                type: string
                default: 'username'
            password:
                type: string
                default: 'password'
            presenter:
                type: boolean
                default: true
            expire:
                type: string
                default: '1h'
    TokenResponse:
        type: 'object'
        properties:
            token:
                type: string
    Peer:
        type: object
        properties:
            peer_name:
                type: string
            peer_avatar:
                type: string
            peer_presenter:
                type: boolean
            peer_video:
                type: boolean
            peer_audio:
                type: boolean
            peer_video_status:
                type: boolean
            peer_audio_status:
                type: boolean
            peer_screen_status:
                type: boolean
            peer_hand_status:
                type: boolean
            peer_privacy_status:
                type: boolean
            os:
                type: string
            browser:
                type: string

    Meeting:
        type: object
        properties:
            roomId:
                type: string
            peers:
                type: array
                items:
                    $ref: '#/definitions/Peer'