reolink-camera-api-openapi.yaml

openapi: 3.0.3
info:
  title: Reolink Camera HTTP API
  description: |
    HTTP and HTTPS based application programming interface for Reolink IPC and NVR products.
    
    This API covers the following modules:
    - System: Device information, time, maintenance, upgrades
    - Security: Authentication, user management
    - Network: Network configuration, email, FTP, push notifications
    - Video Input: Image settings, OSD, ISP, masking
    - Encoding: Video encoding configuration
    - Recording: Recording configuration and playback
    - PTZ: Pan-Tilt-Zoom control and presets
    - Alarm: Motion detection and alarm configuration
    - LED: LED and light control
    - AI: AI detection and tracking
    
    ## Authentication
    
    The API supports two authentication methods:
    
    1. **Long Session (Token-based)**: First obtain a token via the Login endpoint, then include it in subsequent requests
    2. **Short Session**: Include username and password in each request URL
    
    ## Request Format
    
    All requests use POST method to `/cgi-bin/api.cgi` with JSON payload.
    
    Request structure:
    ```json
    [{
      "cmd": "CommandName",
      "action": 0 or 1,
      "param": {
        "field": "value"
      }
    }]
    ```
    
    Where `action`:
    - 0: Get only current values
    - 1: Get initial values, ranges, and current values
    
    ## Response Format
    
    Response structure:
    ```json
    [{
      "cmd": "CommandName",
      "code": 0,
      "value": {
        "field": "value"
      }
    }]
    ```
    
    Where `code`:
    - 0: Success
    - Non-zero: Error (see error codes)

    ## Video Streaming / Preview

    Reolink cameras support RTSP, RTMP, and FLV video streaming protocols.

    **Note**: RTMP and FLV only support H.264 encoding. RTSP supports both H.264 and H.265.

    ### RTSP Streaming

    The RTSP port (default 554) must be enabled in camera settings before use.

    **Current URL Format (Recommended)**:

    **Main Stream**:
    ```
    rtsp://{username}:{password}@{ip_address}:554/Preview_{channel}_main
    ```

    **Sub Stream**:
    ```
    rtsp://{username}:{password}@{ip_address}:554/Preview_{channel}_sub
    ```

    **Important**: Channel numbers start from **01** (e.g., 01, 02, 03) for RTSP URLs.

    **Example**: `rtsp://admin:password@192.168.1.100:554/Preview_01_main`

    **Legacy URL Formats (Still Compatible)**:

    These historical formats are no longer recommended but still supported:

    **Main Stream (H.264)**:
    ```
    rtsp://{username}:{password}@{ip_address}:554/h264Preview_{channel}_main
    ```

    **Main Stream (H.265)**:
    ```
    rtsp://{username}:{password}@{ip_address}:554/h265Preview_{channel}_main
    ```

    **Sub Stream (H.264)**:
    ```
    rtsp://{username}:{password}@{ip_address}:554/h264Preview_{channel}_sub
    ```

    ### RTMP Streaming

    The RTMP port must be enabled in camera settings before use. Only H.264 encoding is supported.

    **Main Stream URL**:
    ```
    rtmp://{ip_address}/bcs/channel{channel_id}_main.bcs?channel={channel_id}&stream=0&user={username}&password={password}
    ```

    **Ext Stream URL**:
    ```
    rtmp://{ip_address}/bcs/channel{channel_id}_ext.bcs?channel={channel_id}&stream=0&user={username}&password={password}
    ```

    **Sub Stream URL**:
    ```
    rtmp://{ip_address}/bcs/channel{channel_id}_sub.bcs?channel={channel_id}&stream=1&user={username}&password={password}
    ```

    **Important**: Channel IDs start from **0** (e.g., 0, 1, 2) for RTMP URLs.

    **Example**: `rtmp://192.168.1.100/bcs/channel0_main.bcs?channel=0&stream=0&user=admin&password=password`

    ### FLV Streaming

    Only H.264 encoding is supported.

    **Main Stream URL**:
    ```
    https://{ip_address}/flv?port=1935&app=bcs&stream=channel{channel_id}_main.bcs&user={username}&password={password}
    ```

    **Ext Stream URL**:
    ```
    https://{ip_address}/flv?port=1935&app=bcs&stream=channel{channel_id}_ext.bcs&user={username}&password={password}
    ```

    **Sub Stream URL**:
    ```
    https://{ip_address}/flv?port=1935&app=bcs&stream=channel{channel_id}_sub.bcs&user={username}&password={password}
    ```

    **Important**: Channel IDs start from **0** (e.g., 0, 1, 2) for FLV URLs.

    **Example**: `https://192.168.1.100/flv?port=1935&app=bcs&stream=channel0_main.bcs&user=admin&password=password`

  version: "8.0"
  contact:
    name: Reolink
  license:
    name: Proprietary
  
servers:
  - url: https://{camera_ip}
    description: HTTPS endpoint (recommended)
    variables:
      camera_ip:
        default: 192.168.1.100
        description: IP address of the camera or NVR
  - url: http://{camera_ip}
    description: HTTP endpoint (must be enabled in camera settings)
    variables:
      camera_ip:
        default: 192.168.1.100
        description: IP address of the camera or NVR

security:
  - tokenAuth: []
  - basicAuth: []

components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: Token obtained from Login endpoint (valid for 3600 seconds)
    
    basicAuth:
      type: http
      scheme: basic
      description: Username and password for short session access
  
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                cmd:
                  type: string
                code:
                  type: integer
                  enum: [0]
                error:
                  $ref: '#/components/schemas/ErrorDetail'
          examples:
            parameterError:
              value:
                - cmd: GetDevInfo
                  code: 0
                  error:
                    rspCode: -4
                    detail: param error
            loginRequired:
              value:
                - cmd: GetDevInfo
                  code: 0
                  error:
                    rspCode: -6
                    detail: please login first
            notSupported:
              value:
                - cmd: SomeCommand
                  code: 0
                  error:
                    rspCode: -9
                    detail: not support

  parameters:
    cmdParam:
      name: cmd
      in: query
      required: true
      schema:
        type: string
      description: Command name to execute

    tokenParam:
      name: token
      in: query
      required: false
      schema:
        type: string
      description: Authentication token (for long session)

    userParam:
      name: user
      in: query
      required: false
      schema:
        type: string
      description: Username (for short session)

    passwordParam:
      name: password
      in: query
      required: false
      schema:
        type: string
      description: Password (for short session)

  schemas:
    # Common request/response structures
    
    BaseRequest:
      type: array
      items:
        type: object
        required:
          - cmd
        properties:
          cmd:
            type: string
            description: Command name
          action:
            type: integer
            enum: [0, 1]
            description: "0: get value only, 1: get initial, range, and value"
          param:
            type: object
            description: Command-specific parameters
    
    BaseResponse:
      type: array
      items:
        type: object
        required:
          - cmd
          - code
        properties:
          cmd:
            type: string
            description: Command name
          code:
            type: integer
            description: Response code (0 = success, non-zero = error)
          value:
            type: object
            description: Response data (present when code = 0)
          error:
            $ref: '#/components/schemas/ErrorDetail'
          initial:
            type: object
            description: Initial/default values (when action = 1)
          range:
            type: object
            description: Valid ranges/options (when action = 1)
    
    ErrorDetail:
      type: object
      properties:
        rspCode:
          type: integer
          description: |
            Detailed error code:

            **General Errors (-1 to -49):**
            * -1: Missing parameters
            * -2: Used up memory
            * -3: Check error
            * -4: Parameters error
            * -5: Reached the max session number
            * -6: Login required
            * -7: Login error
            * -8: Operation timeout
            * -9: Not supported
            * -10: Protocol error
            * -11: Failed to read operation
            * -12: Failed to get configuration
            * -13: Failed to set configuration
            * -14: Failed to apply for memory
            * -15: Failed to created socket
            * -16: Failed to send data
            * -17: Failed to receiver data
            * -18: Failed to open file
            * -19: Failed to read file
            * -20: Failed to write file
            * -21: Token error
            * -22: The length of the string exceeds the limitation
            * -23: Missing parameters
            * -24: Command error
            * -25: Internal error
            * -26: Ability error
            * -27: Invalid user
            * -28: User already exist
            * -29: Reached the maximum number of users
            * -30: The version is identical to the current one
            * -31: Ensure only one user can upgrade (busy)
            * -32: Modify IP conflicted with used IP
            * -34: Cloud login need bind email first
            * -35: Cloud login unbind camera
            * -36: Cloud login get information out of time
            * -37: Cloud login password error
            * -38: Cloud bind camera uid error
            * -39: Cloud login user doesn't exist
            * -40: Cloud unbind camera failed
            * -41: The device doesn't support cloud
            * -42: Cloud login server failed
            * -43: Cloud bind camera failed
            * -44: Cloud unknown error
            * -45: Cloud bind camera need verify code
            * -46: Digest authentication failed
            * -47: Digest authentication Nonce expires
            * -48: Snap a picture failed
            * -49: Channel is invalid
            * -99: Device offline
            * -100: Test Email/Ftp/Wifi failed

            **Upgrade Errors (-101 to -105):**
            * -101: Upgrade checking firmware failed
            * -102: Upgrade download online failed
            * -103: Upgrade get upgrade status failed
            * -105: Frequent logins, please try again later

            **Video Recording Errors (-220 to -222):**
            * -220: Error downloading video file
            * -221: Busy video recording task
            * -222: The video file does not exist

            **Authentication Errors (-301, -310):**
            * -301: Digest Authentication nonce error
            * -310: AES decryption failure

            **FTP Errors (-451 to -454):**
            * -451: FTP test login failed
            * -452: Create FTP directory failed
            * -453: Upload FTP file failed
            * -454: Cannot connect FTP server

            **Email Errors (-480 to -485):**
            * -480: Email undefined error (some undefined errors)
            * -481: Cannot connect email server
            * -482: Email auth user failed
            * -483: Email network error
            * -484: Something wrong with email server
            * -485: Something wrong with memory

            **Login Errors (-500 to -507):**
            * -500: The number of IP addresses reaches the upper limit
            * -501: The user does not exist
            * -502: Password error
            * -503: Login deny
            * -505: Login not init
            * -506: Login locked
            * -507: The number of logins reached the upper limit
          enum: [-1, -2, -3, -4, -5, -6, -7, -8, -9, -10, -11, -12, -13, -14, -15, -16, -17, -18, -19, -20, -21, -22, -23, -24, -25, -26, -27, -28, -29, -30, -31, -32, -34, -35, -36, -37, -38, -39, -40, -41, -42, -43, -44, -45, -46, -47, -48, -49, -99, -100, -101, -102, -103, -105, -220, -221, -222, -301, -310, -451, -452, -453, -454, -480, -481, -482, -483, -484, -485, -500, -501, -502, -503, -505, -506, -507]
        detail:
          type: string
          description: Error description text
          example: param error
    
    # Common data structures
    
    Channel:
      type: object
      properties:
        channel:
          type: integer
          minimum: 0
          description: Channel number (0-based)
    
    Schedule:
      type: object
      description: |
        Weekly schedule configuration.

        **Schedule Table Format:**
        - The table is a string with length of **168 characters** (7 days × 24 hours)
        - Each character represents one hour
        - '0' = feature disabled for that hour
        - Non-zero (typically '1') = feature enabled for that hour
        - Characters are ordered: Sunday hour 0-23, Monday hour 0-23, ..., Saturday hour 0-23

        **Example:** A string of 168 '1's means enabled 24/7
      properties:
        enable:
          type: integer
          enum: [0, 1]
          description: "0: schedule disabled, 1: schedule enabled"
        table:
          type: string
          minLength: 168
          maxLength: 168
          pattern: '^[0-9]{168}$'
          description: |
            Schedule table string (168 characters).
            Each character represents one hour of the week.
          example: "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111"
    
    StreamConfig:
      type: object
      properties:
        vType:
          type: string
          enum: [h264, h265]
          description: Video codec type
        size:
          type: string
          description: Resolution (e.g., "3840*2160")
        width:
          type: integer
          description: Video width in pixels
        height:
          type: integer
          description: Video height in pixels
        frameRate:
          type: integer
          description: Frames per second
        bitRate:
          type: integer
          description: Bitrate in kbps
        gop:
          type: integer
          description: Group of pictures interval
        profile:
          type: string
          enum: [Base, Main, High]
          description: H.264/H.265 profile

    DeviceInfo:
      type: object
      description: Device information
      properties:
        B485:
          type: integer
          description: "0: no RS485, 1: has RS485"
        IOInputNum:
          type: integer
          description: Number of IO input ports
        IOOutputNum:
          type: integer
          description: Number of IO output ports
        audioNum:
          type: integer
          description: Number of audio channels
        buildDay:
          type: string
          description: Build date
        cfgVer:
          type: string
          description: Configuration version
        channelNum:
          type: integer
          description: Number of channels
        detail:
          type: string
          description: Detailed device information
        diskNum:
          type: integer
          description: Number of disks (USB/SD card)
        exactType:
          type: string
          description: Exact product type
        firmVer:
          type: string
          description: Firmware version
        frameworkVer:
          type: integer
          description: Framework/architecture version
        hardVer:
          type: string
          description: Hardware version
        model:
          type: string
          description: Device model
        name:
          type: string
          description: Device name
        pakSuffix:
          type: string
          description: Firmware package suffix
        serial:
          type: string
          description: Serial number
        type:
          type: string
          description: Device type (IPC/NVR)
        wifi:
          type: integer
          description: "0: no WiFi, 1: has WiFi"

    DstConfig:
      type: object
      description: Daylight Saving Time configuration
      properties:
        enable:
          type: integer
          enum: [0, 1]
          description: "0: disabled, 1: enabled"
        offset:
          type: integer
          minimum: 1
          maximum: 2
          description: Time offset in hours
        startMon:
          type: integer
          minimum: 1
          maximum: 12
          description: DST start month (1-12)
        startWeek:
          type: integer
          minimum: 1
          maximum: 5
          description: DST start week of month (1-5)
        startWeekday:
          type: integer
          minimum: 0
          maximum: 6
          description: DST start day of week (0-6, 0=Sunday)
        startHour:
          type: integer
          minimum: 0
          maximum: 23
          description: DST start hour (0-23)
        startMin:
          type: integer
          minimum: 0
          maximum: 59
          description: DST start minute (0-59)
        startSec:
          type: integer
          minimum: 0
          maximum: 59
          description: DST start second (0-59)
        endMon:
          type: integer
          minimum: 1
          maximum: 12
          description: DST end month (1-12)
        endWeek:
          type: integer
          minimum: 1
          maximum: 5
          description: DST end week of month (1-5)
        endWeekday:
          type: integer
          minimum: 0
          maximum: 6
          description: DST end day of week (0-6, 0=Sunday)
        endHour:
          type: integer
          minimum: 0
          maximum: 23
          description: DST end hour (0-23)
        endMin:
          type: integer
          minimum: 0
          maximum: 59
          description: DST end minute (0-59)
        endSec:
          type: integer
          minimum: 0
          maximum: 59
          description: DST end second (0-59)

    TimeConfig:
      type: object
      description: System time configuration
      properties:
        year:
          type: integer
          minimum: 1900
          maximum: 2100
          description: Year (1900-2100)
        mon:
          type: integer
          minimum: 1
          maximum: 12
          description: Month (1-12)
        day:
          type: integer
          minimum: 1
          maximum: 31
          description: Day of month (1-31)
        hour:
          type: integer
          minimum: 0
          maximum: 23
          description: Hour (0-23)
        min:
          type: integer
          minimum: 0
          maximum: 59
          description: Minute (0-59)
        sec:
          type: integer
          minimum: 0
          maximum: 59
          description: Second (0-59)
        timeZone:
          type: integer
          minimum: -46800
          maximum: 43200
          description: Time zone offset in seconds from UTC (-46800 to 43200)
        timeFmt:
          type: string
          enum: ["MM/DD/YYYY", "YYYY/MM/DD", "DD/MM/YYYY"]
          description: Date format
        hourFmt:
          type: integer
          enum: [0, 1]
          description: "0: 24-hour clock, 1: 12-hour clock"

paths:
  # ==================== SYSTEM ENDPOINTS ====================

  /api.cgi:
    post:
      tags:
        - System
      summary: Execute API commands
      description: |
        Main endpoint for all API commands. The specific command is determined by the `cmd` query parameter.
        This documentation breaks down commands by functional area.
      operationId: executeCommand
      parameters:
        - $ref: '#/components/parameters/cmdParam'
        - $ref: '#/components/parameters/tokenParam'
        - $ref: '#/components/parameters/userParam'
        - $ref: '#/components/parameters/passwordParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BaseRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'

  # System Module Endpoints

  /api.cgi?cmd=GetAbility:
    post:
      tags:
        - System
      summary: Get system abilities
      description: |
        Get system ability of appointed user to determine which features are supported.

        **Important Notes:**
        - Each domain corresponds to a functional module
        - The `permit` field marks access rights using the least significant 3 bits:
          - Bit 0 (value 1): Execute/Option permission
          - Bit 1 (value 2): Write/Revision permission
          - Bit 2 (value 4): Read permission
          - Combined value 6 (4+2): Read and Write
          - Combined value 7 (4+2+1): Read, Write, and Execute
        - The `ver` field indicates version number:
          - 0: Feature not supported in this version
          - Non-zero: Feature supported (different versions may support different options)

        **Key Capability Fields:**
        - `abilityChn`: Array of per-channel capabilities (50+ fields including AI detection, PTZ, encoding, ISP settings, etc.)
        - System-level capabilities: auth, time, network, storage, alarms, etc.

        **Common abilityChn Fields:**
        - `supportAi`, `supportAiPeople`, `supportAiVehicle`, `supportAiDogCat`, `supportAiFace`: AI detection capabilities
        - `ptzCtrl`, `ptzPreset`, `ptzPatrol`: PTZ control capabilities
        - `enc`, `live`: Encoding and streaming capabilities
        - `image`, `isp`: Image and ISP parameter configuration
        - `alarmMd`, `alarmAudio`: Motion detection and audio alarm
        - `mask`, `osd`, `waterMark`: Privacy mask, OSD, watermark
        - `recCfg`, `recSchedule`: Recording configuration

        Refer to the PDF documentation for the complete list of 100+ capability fields and their meanings.
      operationId: getAbility
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAbility]
                  param:
                    type: object
                    properties:
                      User:
                        type: object
                        properties:
                          userName:
                            type: string
                            maxLength: 32
                            description: User name (max 32 characters). If NULL, gets current user ability.
            example:
              - cmd: GetAbility
                param:
                  User:
                    userName: admin
      responses:
        '200':
          description: Successful response with ability information
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: GetAbility
                    code:
                      type: integer
                      example: 0
                    value:
                      type: object
                      properties:
                        Ability:
                          type: object
                          description: |
                            Comprehensive ability structure with 100+ capability fields.
                            Each field has `permit` (access rights) and `ver` (version/support) properties.
                          properties:
                            abilityChn:
                              type: array
                              description: Per-channel capabilities array
                              items:
                                type: object
                                description: Channel-specific capabilities (50+ fields)
                            auth:
                              type: object
                              properties:
                                permit:
                                  type: integer
                                ver:
                                  type: integer
                            time:
                              type: object
                              properties:
                                permit:
                                  type: integer
                                ver:
                                  type: integer
                            user:
                              type: object
                              properties:
                                permit:
                                  type: integer
                                ver:
                                  type: integer
                          additionalProperties:
                            type: object
                            description: Additional capability fields (see PDF for complete list)

  /api.cgi?cmd=GetDevInfo:
    post:
      tags:
        - System
      summary: Get device information
      description: Get device information including model, firmware version, hardware version, etc.
      operationId: getDevInfo
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetDevInfo]
            example:
              - cmd: GetDevInfo
      responses:
        '200':
          description: Device information
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        DevInfo:
                          $ref: '#/components/schemas/DeviceInfo'

  /api.cgi?cmd=GetDevName:
    post:
      tags:
        - System
      summary: Get device name
      description: Get the configured device name
      operationId: getDevName
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetDevName]
                  param:
                    type: object
                    required:
                      - channel
                    properties:
                      channel:
                        type: integer
                        description: Index of channel
            example:
              - cmd: GetDevName
                param:
                  channel: 0
      responses:
        '200':
          description: Device name
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        DevName:
                          type: object
                          properties:
                            name:
                              type: string

  /api.cgi?cmd=SetDevName:
    post:
      tags:
        - System
      summary: Set device name
      description: Set the device name
      operationId: setDevName
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetDevName]
                  param:
                    type: object
                    properties:
                      DevName:
                        type: object
                        properties:
                          name:
                            type: string
            example:
              - cmd: SetDevName
                param:
                  DevName:
                    name: camera101
      responses:
        '200':
          description: Success response

  /api.cgi?cmd=GetTime:
    post:
      tags:
        - System
      summary: Get time configuration
      description: |
        Get time and timezone configuration from device including DST (Daylight Saving Time) settings.

        Use `action: 1` to get initial values, ranges, and current values.
        Use `action: 0` to get only current values.
      operationId: getTime
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetTime]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetTime
                action: 1
      responses:
        '200':
          description: Time configuration with DST settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: GetTime
                    code:
                      type: integer
                      example: 0
                    initial:
                      type: object
                      description: Initial/default values (when action=1)
                      properties:
                        Dst:
                          $ref: '#/components/schemas/DstConfig'
                        Time:
                          $ref: '#/components/schemas/TimeConfig'
                    range:
                      type: object
                      description: Valid ranges for each field (when action=1)
                    value:
                      type: object
                      description: Current values
                      properties:
                        Dst:
                          $ref: '#/components/schemas/DstConfig'
                        Time:
                          $ref: '#/components/schemas/TimeConfig'

  /api.cgi?cmd=SetTime:
    post:
      tags:
        - System
      summary: Set time configuration
      description: |
        Set time, timezone, and DST (Daylight Saving Time) configuration.

        **Note:** All parameters are optional (O). You can set only the fields you want to change.
      operationId: setTime
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetTime]
                  param:
                    type: object
                    properties:
                      Dst:
                        $ref: '#/components/schemas/DstConfig'
                      Time:
                        $ref: '#/components/schemas/TimeConfig'
            example:
              - cmd: SetTime
                param:
                  Dst:
                    enable: 0
                    offset: 1
                    startMon: 3
                    startWeek: 2
                    startWeekday: 0
                    startHour: 2
                    startMin: 0
                    startSec: 0
                    endMon: 10
                    endWeek: 5
                    endWeekday: 0
                    endHour: 2
                    endMin: 0
                    endSec: 0
                  Time:
                    year: 2023
                    mon: 6
                    day: 15
                    hour: 14
                    min: 30
                    sec: 0
                    timeZone: -28800
                    timeFmt: "DD/MM/YYYY"
                    hourFmt: 0
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: SetTime
                    code:
                      type: integer
                      example: 0
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          example: 200

  /api.cgi?cmd=GetAutoMaint:
    post:
      tags:
        - System
      summary: Get auto maintenance configuration
      description: Get automatic maintenance settings (auto reboot)
      operationId: getAutoMaint
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAutoMaint]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetAutoMaint
                action: 1
      responses:
        '200':
          description: Auto maintenance configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        AutoMaint:
                          type: object
                          properties:
                            enable:
                              type: integer
                              enum: [0, 1]
                              description: Enable automatic maintenance
                            hour:
                              type: integer
                              minimum: 0
                              maximum: 23
                              description: Hour of day for maintenance
                            min:
                              type: integer
                              minimum: 0
                              maximum: 59
                              description: Minute of hour for maintenance
                            sec:
                              type: integer
                              minimum: 0
                              maximum: 59
                              description: Second of minute for maintenance
                            weekDay:
                              type: string
                              enum: ["Everyday", "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
                              description: Day of week for maintenance

  /api.cgi?cmd=SetAutoMaint:
    post:
      tags:
        - System
      summary: Set auto maintenance configuration
      description: Set automatic maintenance settings
      operationId: setAutoMaint
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Success response

  /api.cgi?cmd=GetHddInfo:
    post:
      tags:
        - System
      summary: Get HDD information
      description: Get hard disk drive or SD card information
      operationId: getHddInfo
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetHddInfo]
      responses:
        '200':
          description: HDD information
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        HddInfo:
                          type: array
                          description: List of storage devices
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                description: Storage device ID
                              name:
                                type: string
                                description: Device name
                              capacity:
                                type: integer
                                description: Total capacity in MB
                              size:
                                type: integer
                                description: Used size in MB
                              format:
                                type: integer
                                enum: [0, 1]
                                description: Format status (0=not formatted, 1=formatted)
                              mount:
                                type: integer
                                enum: [0, 1]
                                description: Mount status (0=not mounted, 1=mounted)

  /api.cgi?cmd=Format:
    post:
      tags:
        - System
      summary: Format storage
      description: Format HDD or SD card
      operationId: format
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [Format]
                  param:
                    type: object
                    properties:
                      HddInfo:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: Storage device ID to format
            example:
              - cmd: Format
                param:
                  HddInfo:
                    id: 0
      responses:
        '200':
          description: Format initiated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=Upgrade:
    post:
      tags:
        - System
      summary: Upgrade firmware
      description: |
        Upload and install firmware upgrade.

        **Important Limitation:** This command can only carry up to **40K packets at a time**.
        It needs to be called several times to complete the device update for larger firmware files.

        The firmware file should be sent as multipart/form-data with the field name "upgrade-package".
      operationId: upgrade
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                upgrade-package:
                  type: string
                  format: binary
                  description: Firmware package file (.pak)
      responses:
        '200':
          description: Upgrade initiated

  /api.cgi?cmd=Restore:
    post:
      tags:
        - System
      summary: Restore factory defaults
      description: Restore device to factory default settings
      operationId: restore
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [Restore]
      responses:
        '200':
          description: Restore initiated

  /api.cgi?cmd=Reboot:
    post:
      tags:
        - System
      summary: Reboot device
      description: Reboot the camera or NVR
      operationId: reboot
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [Reboot]
      responses:
        '200':
          description: Reboot initiated

  /api.cgi?cmd=UpgradePrepare:
    post:
      tags:
        - System
      summary: Prepare for upgrade
      description: Prepare device for firmware upgrade
      operationId: upgradePrepare
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [UpgradePrepare]
                  param:
                    type: object
                    required:
                      - restoreCfg
                      - fileName
                    properties:
                      restoreCfg:
                        type: integer
                        enum: [0, 1]
                        description: Whether to restore configuration (0=no, 1=yes)
                      fileName:
                        type: string
                        description: Firmware file name (e.g., "XXX.pak")
            example:
              - cmd: UpgradePrepare
                param:
                  restoreCfg: 0
                  fileName: "XXX.pak"
      responses:
        '200':
          description: Preparation complete

  /api.cgi?cmd=GetAutoUpgrade:
    post:
      tags:
        - System
      summary: Get auto upgrade configuration
      description: Get automatic upgrade settings
      operationId: getAutoUpgrade
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAutoUpgrade]
      responses:
        '200':
          description: Auto upgrade configuration

  /api.cgi?cmd=SetAutoUpgrade:
    post:
      tags:
        - System
      summary: Set auto upgrade configuration
      description: Set automatic upgrade settings
      operationId: setAutoUpgrade
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Success response

  /api.cgi?cmd=CheckFirmware:
    post:
      tags:
        - System
      summary: Check for firmware updates
      description: Check if new firmware is available
      operationId: checkFirmware
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [CheckFirmware]
      responses:
        '200':
          description: Firmware check result

  /api.cgi?cmd=UpgradeOnline:
    post:
      tags:
        - System
      summary: Upgrade firmware online
      description: Download and install firmware from online source
      operationId: upgradeOnline
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Online upgrade initiated

  /api.cgi?cmd=UpgradeStatus:
    post:
      tags:
        - System
      summary: Get upgrade status
      description: Get current firmware upgrade status
      operationId: upgradeStatus
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [UpgradeStatus]
      responses:
        '200':
          description: Upgrade status

  /api.cgi?cmd=Getchannelstatus:
    post:
      tags:
        - System
      summary: Get channel status
      description: Get status of all channels (for NVR)
      operationId: getChannelStatus
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [Getchannelstatus]
      responses:
        '200':
          description: Channel status information

  # ==================== SECURITY ENDPOINTS ====================

  /api.cgi?cmd=Login:
    post:
      tags:
        - Security
      summary: Login and get token
      description: |
        Authenticate with username and password to obtain an authentication token.
        The token is valid for 3600 seconds (1 hour) and must be included in subsequent requests.
      operationId: login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - cmd
                  - param
                properties:
                  cmd:
                    type: string
                    enum: [Login]
                  param:
                    type: object
                    required:
                      - User
                    properties:
                      User:
                        type: object
                        required:
                          - userName
                          - password
                        properties:
                          userName:
                            type: string
                            minLength: 1
                            maxLength: 31
                            description: Account name
                          password:
                            type: string
                            minLength: 1
                            maxLength: 31
                            description: Account password
                          Version:
                            type: string
                            enum: ["0", "1"]
                            default: "0"
                            description: "0: no encryption, 1: private encryption (not available externally)"
            example:
              - cmd: Login
                param:
                  User:
                    Version: "0"
                    userName: admin
                    password: "111111"
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Token:
                          type: object
                          properties:
                            leaseTime:
                              type: integer
                              description: Token validity duration in seconds
                            name:
                              type: string
                              maxLength: 32
                              description: Token string to use in subsequent requests
              example:
                - cmd: Login
                  code: 0
                  value:
                    Token:
                      leaseTime: 3600
                      name: "031465962723"

  /api.cgi?cmd=Logout:
    post:
      tags:
        - Security
      summary: Logout
      description: Invalidate the current authentication token
      operationId: logout
      security:
        - tokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [Logout]
            example:
              - cmd: Logout
      responses:
        '200':
          description: Logout successful

  /api.cgi?cmd=GetUser:
    post:
      tags:
        - Security
      summary: Get user list
      description: Get list of all users configured on the device
      operationId: getUser
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetUser]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetUser
                action: 1
      responses:
        '200':
          description: User list with constraints
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: GetUser
                    code:
                      type: integer
                      example: 0
                    range:
                      type: object
                      description: Constraints for user fields
                      properties:
                        User:
                          type: object
                          properties:
                            level:
                              type: array
                              items:
                                type: string
                              example: ["guest", "admin"]
                            password:
                              type: object
                              properties:
                                minLen:
                                  type: integer
                                  example: 6
                                maxLen:
                                  type: integer
                                  example: 31
                            userName:
                              type: object
                              properties:
                                minLen:
                                  type: integer
                                  example: 1
                                maxLen:
                                  type: integer
                                  example: 31
                    value:
                      type: object
                      properties:
                        User:
                          type: array
                          items:
                            type: object
                            properties:
                              userName:
                                type: string
                              level:
                                type: string
                                enum: [admin, guest]

  /api.cgi?cmd=AddUser:
    post:
      tags:
        - Security
      summary: Add user
      description: |
        Add a new user account.

        **Important Constraint:** Can add up to **20 users** maximum.
      operationId: addUser
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [AddUser]
                  param:
                    type: object
                    properties:
                      User:
                        type: object
                        properties:
                          userName:
                            type: string
                            description: Username for the new account
                          password:
                            type: string
                            description: Password for the new account
                          level:
                            type: string
                            enum: [admin, guest]
                            description: User privilege level
            example:
              - cmd: AddUser
                param:
                  User:
                    userName: newuser
                    password: password123
                    level: guest
      responses:
        '200':
          description: User added successfully

  /api.cgi?cmd=DelUser:
    post:
      tags:
        - Security
      summary: Delete user
      description: Delete an existing user account
      operationId: delUser
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [DelUser]
                  param:
                    type: object
                    properties:
                      User:
                        type: object
                        properties:
                          userName:
                            type: string
      responses:
        '200':
          description: User deleted successfully

  /api.cgi?cmd=ModifyUser:
    post:
      tags:
        - Security
      summary: Modify user
      description: |
        Modify an existing user account (change password, level, etc.).

        **Password Constraints:**
        - Minimum length: 6 characters
        - Maximum length: 31 characters
      operationId: modifyUser
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [ModifyUser]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: set value, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      User:
                        type: object
                        properties:
                          userName:
                            type: string
                            minLength: 1
                            maxLength: 31
                            description: Account name to modify
                          newPassword:
                            type: string
                            minLength: 6
                            maxLength: 31
                            description: New password for the account
                          oldPassword:
                            type: string
                            description: Current password (required for verification)
            example:
              - cmd: ModifyUser
                action: 0
                param:
                  User:
                    userName: admin
                    newPassword: "111111"
                    oldPassword: "000000"
      responses:
        '200':
          description: User modified successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: ModifyUser
                    code:
                      type: integer
                      example: 0
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          example: 200

  /api.cgi?cmd=GetOnline:
    post:
      tags:
        - Security
      summary: Get online users
      description: Get list of currently logged in users
      operationId: getOnline
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetOnline]
      responses:
        '200':
          description: Online users list

  /api.cgi?cmd=Disconnect:
    post:
      tags:
        - Security
      summary: Disconnect user
      description: Disconnect a specific online user session
      operationId: disconnect
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [Disconnect]
                  param:
                    type: object
                    properties:
                      User:
                        type: object
                        required:
                          - userName
                          - sessionId
                        properties:
                          userName:
                            type: string
                            description: Username of the session to disconnect
                          sessionId:
                            type: integer
                            description: Session ID to disconnect
            example:
              - cmd: Disconnect
                param:
                  User:
                    userName: userName
                    sessionId: 1001
      responses:
        '200':
          description: User disconnected

  /api.cgi?cmd=GetSysCfg:
    post:
      tags:
        - Security
      summary: Get system configuration
      description: Get system configuration (export configuration)
      operationId: getSysCfg
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetSysCfg]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
            example:
              - cmd: GetSysCfg
                param:
                  channel: 0
      responses:
        '200':
          description: System configuration

  /api.cgi?cmd=SetSysCfg:
    post:
      tags:
        - Security
      summary: Set system configuration
      description: Set system configuration (import configuration)
      operationId: setSysCfg
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Configuration imported successfully

  # ==================== NETWORK ENDPOINTS ====================

  /api.cgi?cmd=GetLocalLink:
    post:
      tags:
        - Network
      summary: Get local network configuration
      description: Get IP address, subnet mask, gateway, and DNS settings
      operationId: getLocalLink
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetLocalLink]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: Network configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        LocalLink:
                          type: object
                          properties:
                            type:
                              type: string
                              enum: ["DHCP", "Static"]
                            static:
                              type: object
                              properties:
                                ip:
                                  type: string
                                mask:
                                  type: string
                                gateway:
                                  type: string
                            dns:
                              type: object
                              properties:
                                auto:
                                  type: integer
                                  enum: [0, 1]
                                dns1:
                                  type: string
                                dns2:
                                  type: string

  /api.cgi?cmd=SetLocalLink:
    post:
      tags:
        - Network
      summary: Set local network configuration
      description: Set IP address, subnet mask, gateway, and DNS settings
      operationId: setLocalLink
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetLocalLink]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: set value, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      LocalLink:
                        type: object
                        properties:
                          type:
                            type: string
                            enum: ["DHCP", "Static"]
                            description: Network IP distribution method
                          static:
                            type: object
                            description: Static IP configuration (required when type is Static)
                            properties:
                              ip:
                                type: string
                                description: IP address
                              mask:
                                type: string
                                description: Subnet mask
                              gateway:
                                type: string
                                description: Gateway address
                          dns:
                            type: object
                            description: DNS configuration
                            properties:
                              auto:
                                type: integer
                                enum: [0, 1]
                                description: Whether to auto get DNS
                              dns1:
                                type: string
                                description: Preferred DNS server
                              dns2:
                                type: string
                                description: Alternate DNS server
            example:
              - cmd: SetLocalLink
                action: 0
                param:
                  LocalLink:
                    type: Static
                    static:
                      ip: "192.168.2.122"
                      mask: "255.255.255.0"
                      gateway: "192.168.2.1"
                    dns:
                      auto: 0
                      dns1: "202.96.128.166"
                      dns2: "202.96.134.133"
      responses:
        '200':
          description: Network configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetDdns:
    post:
      tags:
        - Network
      summary: Get DDNS configuration
      description: Get Dynamic DNS configuration
      operationId: getDdns
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetDdns]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: DDNS configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Ddns:
                          type: object
                          properties:
                            enable:
                              type: integer
                              enum: [0, 1]
                            type:
                              type: string
                              enum: ["3322", "Dyndns"]
                            userName:
                              type: string
                            password:
                              type: string
                            domain:
                              type: string

  /api.cgi?cmd=SetDdns:
    post:
      tags:
        - Network
      summary: Set DDNS configuration
      description: Set Dynamic DNS configuration
      operationId: setDdns
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetDdns]
                  param:
                    type: object
                    properties:
                      Ddns:
                        type: object
                        properties:
                          enable:
                            type: integer
                            enum: [0, 1]
                            description: DDNS enable switch
                          type:
                            type: string
                            enum: ["3322", "Dyndns"]
                            description: DDNS server type
                          userName:
                            type: string
                            description: DDNS username
                          password:
                            type: string
                            description: DDNS password
                          domain:
                            type: string
                            description: The domain which you set
            example:
              - cmd: SetDdns
                param:
                  Ddns:
                    enable: 1
                    type: dyndns
                    userName: username
                    password: password
                    domain: domain
      responses:
        '200':
          description: DDNS configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetEmail:
    post:
      tags:
        - Network
      summary: Get email configuration
      description: |
        Get email notification settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `GetEmailV20` instead for enhanced features.

        **Parameter Details:**
        - **smtpServer**: Email server address (max 127 characters)
        - **smtpPort**: SMTP port (1-65535, default 465 for SSL)
        - **userName**: Sender email address (max 127 characters)
        - **password**: Sender password (max 31 characters)
        - **addr1/addr2/addr3**: Recipient email addresses (max 127 characters each)
        - **attachment**: Email attachment type
          - "no": No attachment
          - "picture": Picture only
          - "video": Video only
          - "onlyPicture": Picture only (alternative)
        - **interval**: Email send interval ["30 Seconds", "1 Minute", "5 Minutes", "10 Minutes", "30 Minutes"]
        - **ssl**: Enable SSL/TLS (boolean)
        - **nickName**: Sender nickname (NVR only, max 127 characters)
      operationId: getEmail
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetEmail]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetEmail
                action: 1
      responses:
        '200':
          description: Email configuration with schedule table
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Email:
                          type: object
                          properties:
                            smtpServer:
                              type: string
                              maxLength: 127
                            smtpPort:
                              type: integer
                              minimum: 1
                              maximum: 65535
                            userName:
                              type: string
                              maxLength: 127
                            password:
                              type: string
                              maxLength: 31
                            addr1:
                              type: string
                              maxLength: 127
                            addr2:
                              type: string
                              maxLength: 127
                            addr3:
                              type: string
                              maxLength: 127
                            attachment:
                              type: string
                              enum: ["no", "picture", "video", "onlyPicture"]
                            interval:
                              type: string
                              enum: ["30 Seconds", "1 Minute", "5 Minutes", "10 Minutes", "30 Minutes"]
                            ssl:
                              type: integer
                              enum: [0, 1]
                            nickName:
                              type: string
                              maxLength: 127
                              description: "NVR only"
                            schedule:
                              $ref: '#/components/schemas/Schedule'

  /api.cgi?cmd=SetEmail:
    post:
      tags:
        - Network
      summary: Set email configuration
      description: |
        Set email notification settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `SetEmailV20` instead for enhanced features.
      operationId: setEmail
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Email configuration updated

  /api.cgi?cmd=GetEmailV20:
    post:
      tags:
        - Network
      summary: Get email configuration (v2.0)
      description: |
        Get email notification settings (version 2.0 with enhanced features).

        **Version Note:** Use this command when `scheduleVersion.ver = 1` in the capability set (from GetAbility).
      operationId: getEmailV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetEmailV20]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: Email configuration (v2.0)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Email:
                          type: object
                          properties:
                            schedule:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                table:
                                  type: object
                                  description: Schedule tables for different alarm types
                                  properties:
                                    MD:
                                      type: string
                                      description: Motion detection schedule (168 chars)
                                    AI_PEOPLE:
                                      type: string
                                      description: AI people detection schedule (168 chars)
                                    AI_VEHICLE:
                                      type: string
                                      description: AI vehicle detection schedule (168 chars)
                                    AI_DOG_CAT:
                                      type: string
                                      description: AI dog/cat detection schedule (168 chars)
                            smtpServer:
                              type: string
                            smtpPort:
                              type: integer
                            userName:
                              type: string
                            password:
                              type: string
                            addr1:
                              type: string
                            addr2:
                              type: string
                            addr3:
                              type: string
                            attachment:
                              type: string
                              enum: ["no", "picture", "video", "onlyPicture"]
                            interval:
                              type: string
                            nickName:
                              type: string
                            ssl:
                              type: integer
                              enum: [0, 1]

  /api.cgi?cmd=SetEmailV20:
    post:
      tags:
        - Network
      summary: Set email configuration (v2.0)
      description: Set email notification settings (version 2.0)
      operationId: setEmailV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Email configuration updated

  /api.cgi?cmd=TestEmail:
    post:
      tags:
        - Network
      summary: Test email configuration
      description: |
        Send a test email to verify email settings.

        **Important Constraint:** At least one of the three addresses (addr1, addr2, addr3) must be provided.
      operationId: testEmail
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [TestEmail]
                  param:
                    type: object
                    required:
                      - Email
                    properties:
                      Email:
                        type: object
                        required:
                          - smtpServer
                          - smtpPort
                          - userName
                          - ssl
                        properties:
                          smtpServer:
                            type: string
                            maxLength: 127
                            description: Email server of sender
                          smtpPort:
                            type: integer
                            minimum: 1
                            maximum: 65535
                            description: Port of Email server
                          userName:
                            type: string
                            maxLength: 127
                            description: Sender address
                          password:
                            type: string
                            maxLength: 31
                            description: Sender password (optional)
                          ssl:
                            type: integer
                            enum: [0, 1]
                            description: Whether to open encryption mode
                          addr1:
                            type: string
                            maxLength: 127
                            description: Receiver address 1 (at least one of addr1/addr2/addr3 required)
                          addr2:
                            type: string
                            maxLength: 127
                            description: Receiver address 2 (at least one of addr1/addr2/addr3 required)
                          addr3:
                            type: string
                            maxLength: 127
                            description: Receiver address 3 (at least one of addr1/addr2/addr3 required)
                          nickName:
                            type: string
                            description: Corresponds to the user name (optional)
                          interval:
                            type: string
                            enum: ["30 Seconds", "1 Minute", "5 Minutes", "10 Minutes", "30 Minutes"]
            example:
              - cmd: TestEmail
                param:
                  Email:
                    smtpServer: smtp.qq.com
                    smtpPort: 465
                    userName: user@qq.com
                    password: password123
                    ssl: 1
                    addr1: recipient@example.com
                    interval: "5 Minutes"
      responses:
        '200':
          description: Test email sent
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetFtp:
    post:
      tags:
        - Network
      summary: Get FTP configuration
      description: |
        Get FTP upload settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `GetFtpV20` instead for enhanced features.

        **Parameter Details:**
        - **mode** (NVR only): 0-2
        - **autoDir** (NVR only): 0 or 1 (boolean)
        - **streamType**: 0 = main stream, 1 = sub stream, 2 = ext stream
        - **interval**: Upload interval in seconds (1-3600)
        - **maxSize**: Maximum file size in MB (10-1024)
        - **port**: FTP port (1-65535, default 21)
      operationId: getFtp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetFtp]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetFtp
                action: 1
      responses:
        '200':
          description: FTP configuration with schedule table
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Ftp:
                          type: object
                          properties:
                            server:
                              type: string
                              maxLength: 127
                            port:
                              type: integer
                              minimum: 1
                              maximum: 65535
                            userName:
                              type: string
                              maxLength: 127
                            password:
                              type: string
                              maxLength: 127
                            remoteDir:
                              type: string
                              maxLength: 255
                            anonymous:
                              type: integer
                              enum: [0, 1]
                            mode:
                              type: integer
                              minimum: 0
                              maximum: 2
                              description: "NVR only: 0-2"
                            autoDir:
                              type: integer
                              enum: [0, 1]
                              description: "NVR only: auto directory creation"
                            streamType:
                              type: integer
                              enum: [0, 1, 2]
                              description: "0: main, 1: sub, 2: ext"
                            interval:
                              type: integer
                              minimum: 1
                              maximum: 3600
                              description: Upload interval in seconds
                            maxSize:
                              type: integer
                              minimum: 10
                              maximum: 1024
                              description: Maximum file size in MB
                            schedule:
                              $ref: '#/components/schemas/Schedule'

  /api.cgi?cmd=SetFtp:
    post:
      tags:
        - Network
      summary: Set FTP configuration
      description: |
        Set FTP upload settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `SetFtpV20` instead for enhanced features.

        **Model Note:** This command supports model 52X only.
      operationId: setFtp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: FTP configuration updated

  /api.cgi?cmd=GetFtpV20:
    post:
      tags:
        - Network
      summary: Get FTP configuration (v2.0)
      description: |
        Get FTP upload settings (version 2.0 with enhanced features).

        **Version Note:** Use this command when `scheduleVersion.ver = 1` in the capability set (from GetAbility).

        **Enhanced Parameters in V20:**
        - **autoDir**: 0-3 (expanded from boolean in v1)
          - 0: No auto directory
          - 1: Auto directory by date
          - 2: Auto directory by camera name
          - 3: Auto directory by date and camera name
        - **picCaptureMode**: 0-3
          - 0: Disabled
          - 1: Capture on motion
          - 2: Capture on schedule
          - 3: Capture on motion and schedule
        - **bpicSingle/bvideoSingle**: 0-2 (picture/video upload mode)
        - **picInterval**: Picture capture interval in seconds [2, 5, 10, 15, 30, 60, 300, 600, 1800]
        - **interval**: Video upload interval [5, 10, 15, 30, 60]
        - **picWidth/picHeight**: Picture dimensions (360-2160 height, up to 3840 width)
      operationId: getFtpV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetFtpV20]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetFtpV20
                action: 1
      responses:
        '200':
          description: FTP configuration (v2.0) with enhanced parameters

  /api.cgi?cmd=SetFtpV20:
    post:
      tags:
        - Network
      summary: Set FTP configuration (v2.0)
      description: Set FTP upload settings (version 2.0)
      operationId: setFtpV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: FTP configuration updated

  /api.cgi?cmd=TestFtp:
    post:
      tags:
        - Network
      summary: Test FTP configuration
      description: Test FTP connection and upload
      operationId: testFtp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [TestFtp]
      responses:
        '200':
          description: FTP test result

  /api.cgi?cmd=GetNtp:
    post:
      tags:
        - Network
      summary: Get NTP configuration
      description: Get Network Time Protocol settings
      operationId: getNtp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetNtp]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: NTP configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Ntp:
                          type: object
                          properties:
                            enable:
                              type: integer
                              enum: [0, 1]
                            server:
                              type: string
                            port:
                              type: integer
                            interval:
                              type: integer
                              description: Sync interval in minutes (0-65535)

  /api.cgi?cmd=SetNtp:
    post:
      tags:
        - Network
      summary: Set NTP configuration
      description: |
        Set Network Time Protocol settings.

        **Note:** Interval limit is 10-65535 minutes, and 0 represents immediate synchronization.
      operationId: setNtp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetNtp]
                  param:
                    type: object
                    properties:
                      Ntp:
                        type: object
                        properties:
                          enable:
                            type: integer
                            enum: [0, 1]
                            description: NTP switch (1=open, 0=closed)
                          server:
                            type: string
                            description: NTP server (IP address or domain name)
                          port:
                            type: integer
                            description: Port of NTP server
                          interval:
                            type: integer
                            minimum: 0
                            maximum: 65535
                            description: Time synchronization interval in minutes (10-65535, 0=immediate sync)
            example:
              - cmd: SetNtp
                param:
                  Ntp:
                    enable: 1
                    server: pool.ntp.org
                    port: 123
                    interval: 1440
      responses:
        '200':
          description: NTP configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetNetPort:
    post:
      tags:
        - Network
      summary: Get network port configuration
      description: Get HTTP, HTTPS, RTSP, RTMP, and ONVIF port settings
      operationId: getNetPort
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetNetPort]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: Network port configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        NetPort:
                          type: object
                          properties:
                            httpEnable:
                              type: integer
                              enum: [0, 1]
                            httpPort:
                              type: integer
                            httpsEnable:
                              type: integer
                              enum: [0, 1]
                            httpsPort:
                              type: integer
                            mediaPort:
                              type: integer
                            onvifEnable:
                              type: integer
                              enum: [0, 1]
                            onvifPort:
                              type: integer
                            rtmpEnable:
                              type: integer
                              enum: [0, 1]
                            rtmpPort:
                              type: integer
                            rtspEnable:
                              type: integer
                              enum: [0, 1]
                            rtspPort:
                              type: integer

  /api.cgi?cmd=SetNetPort:
    post:
      tags:
        - Network
      summary: Set network port configuration
      description: Set HTTP, HTTPS, RTSP, RTMP, and ONVIF port settings
      operationId: setNetPort
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetNetPort]
                  param:
                    type: object
                    properties:
                      NetPort:
                        type: object
                        properties:
                          httpEnable:
                            type: integer
                            enum: [0, 1]
                            description: Enable HTTP
                          httpPort:
                            type: integer
                            description: Port of HTTP
                          httpsEnable:
                            type: integer
                            enum: [0, 1]
                            description: Enable HTTPS
                          httpsPort:
                            type: integer
                            description: Port of HTTPS
                          mediaPort:
                            type: integer
                            description: Port of media
                          onvifEnable:
                            type: integer
                            enum: [0, 1]
                            description: Enable ONVIF
                          onvifPort:
                            type: integer
                            description: Port of ONVIF
                          rtmpEnable:
                            type: integer
                            enum: [0, 1]
                            description: Enable RTMP
                          rtmpPort:
                            type: integer
                            description: Port of RTMP
                          rtspEnable:
                            type: integer
                            enum: [0, 1]
                            description: Enable RTSP
                          rtspPort:
                            type: integer
                            description: Port of RTSP
            example:
              - cmd: SetNetPort
                param:
                  NetPort:
                    httpEnable: 0
                    httpPort: 80
                    httpsEnable: 1
                    httpsPort: 443
                    mediaPort: 9000
                    onvifEnable: 1
                    onvifPort: 8000
                    rtmpEnable: 0
                    rtmpPort: 1935
                    rtspEnable: 1
                    rtspPort: 554
      responses:
        '200':
          description: Network port configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetUpnp:
    post:
      tags:
        - Network
      summary: Get UPnP configuration
      description: Get Universal Plug and Play settings
      operationId: getUpnp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetUpnp]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: UPnP configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Upnp:
                          type: object
                          properties:
                            enable:
                              type: integer
                              enum: [0, 1]

  /api.cgi?cmd=SetUpnp:
    post:
      tags:
        - Network
      summary: Set UPnP configuration
      description: Set Universal Plug and Play settings
      operationId: setUpnp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetUpnp]
                  param:
                    type: object
                    properties:
                      Upnp:
                        type: object
                        properties:
                          enable:
                            type: integer
                            enum: [0, 1]
                            description: UPnP switch (1=open, 0=closed)
            example:
              - cmd: SetUpnp
                param:
                  Upnp:
                    enable: 1
      responses:
        '200':
          description: UPnP configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetWifi:
    post:
      tags:
        - Network
      summary: Get WiFi configuration
      description: Get WiFi network settings
      operationId: getWifi
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetWifi]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: WiFi configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Wifi:
                          type: object
                          properties:
                            ssid:
                              type: string
                            password:
                              type: string

  /api.cgi?cmd=SetWifi:
    post:
      tags:
        - Network
      summary: Set WiFi configuration
      description: Set WiFi network settings
      operationId: setWifi
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetWifi]
                  param:
                    type: object
                    properties:
                      Wifi:
                        type: object
                        properties:
                          ssid:
                            type: string
                            description: The name of the wireless network
                          password:
                            type: string
                            description: The password of the wireless network
            example:
              - cmd: SetWifi
                param:
                  Wifi:
                    ssid: ssid
                    password: "000000"
      responses:
        '200':
          description: WiFi configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=TestWifi:
    post:
      tags:
        - Network
      summary: Test WiFi connection
      description: Test WiFi connection with specified settings
      operationId: testWifi
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: WiFi test result

  /api.cgi?cmd=ScanWifi:
    post:
      tags:
        - Network
      summary: Scan for WiFi networks
      description: Scan for available WiFi networks
      operationId: scanWifi
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [ScanWifi]
      responses:
        '200':
          description: List of available WiFi networks

  /api.cgi?cmd=GetWifiSignal:
    post:
      tags:
        - Network
      summary: Get WiFi signal strength
      description: Get current WiFi signal strength
      operationId: getWifiSignal
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetWifiSignal]
      responses:
        '200':
          description: WiFi signal strength

  /api.cgi?cmd=GetPush:
    post:
      tags:
        - Network
      summary: Get push notification configuration
      description: |
        Get push notification settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `GetPushV20` instead for enhanced features.

        **Parameter Details:**
        - **schedule.enable**: Whether to push alarm information (boolean)
        - **schedule.table**: 168-character schedule string (7 days × 24 hours)
      operationId: getPush
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPush]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetPush
                action: 1
      responses:
        '200':
          description: Push notification configuration with schedule
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Push:
                          type: object
                          properties:
                            schedule:
                              $ref: '#/components/schemas/Schedule'

  /api.cgi?cmd=SetPush:
    post:
      tags:
        - Network
      summary: Set push notification configuration
      description: |
        Set push notification settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `SetPushV20` instead for enhanced features.

        **Model Note:** This command supports model 52X only.
      operationId: setPush
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Push notification configuration updated

  /api.cgi?cmd=GetPushV20:
    post:
      tags:
        - Network
      summary: Get push notification configuration (v2.0)
      description: |
        Get push notification settings (version 2.0 with enhanced features).

        **Version Note:** Use this command when `scheduleVersion.ver = 1` in the capability set (from GetAbility).
      operationId: getPushV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPushV20]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: Push notification configuration (v2.0)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Push:
                          type: object
                          properties:
                            schedule:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                table:
                                  type: object
                                  description: Schedule tables for different alarm types
                                  properties:
                                    MD:
                                      type: string
                                      description: Motion detection schedule (168 chars)
                                    AI_PEOPLE:
                                      type: string
                                      description: AI people detection schedule (168 chars)
                                    AI_VEHICLE:
                                      type: string
                                      description: AI vehicle detection schedule (168 chars)
                                    AI_DOG_CAT:
                                      type: string
                                      description: AI dog/cat detection schedule (168 chars)

  /api.cgi?cmd=SetPushV20:
    post:
      tags:
        - Network
      summary: Set push notification configuration (v2.0)
      description: Set push notification settings (version 2.0)
      operationId: setPushV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Push notification configuration updated

  /api.cgi?cmd=GetPushCfg:
    post:
      tags:
        - Network
      summary: Get push configuration
      description: Get push notification configuration details
      operationId: getPushCfg
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPushCfg]
      responses:
        '200':
          description: Push configuration

  /api.cgi?cmd=SetPushCfg:
    post:
      tags:
        - Network
      summary: Set push configuration
      description: Set push notification configuration details
      operationId: setPushCfg
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Push configuration updated

  /api.cgi?cmd=GetP2p:
    post:
      tags:
        - Network
      summary: Get P2P configuration
      description: Get Peer-to-Peer connection settings
      operationId: getP2p
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetP2p]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: P2P configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        P2p:
                          type: object
                          properties:
                            enable:
                              type: integer
                              enum: [0, 1]

  /api.cgi?cmd=SetP2p:
    post:
      tags:
        - Network
      summary: Set P2P configuration
      description: Set Peer-to-Peer connection settings
      operationId: setP2p
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetP2p]
                  param:
                    type: object
                    properties:
                      P2p:
                        type: object
                        properties:
                          enable:
                            type: integer
                            enum: [0, 1]
                            description: Whether to enable P2P
            example:
              - cmd: SetP2p
                param:
                  P2p:
                    enable: 0
      responses:
        '200':
          description: P2P configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetCertificateInfo:
    post:
      tags:
        - Network
      summary: Get certificate information
      description: Get SSL/TLS certificate information
      operationId: getCertificateInfo
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetCertificateInfo]
      responses:
        '200':
          description: Certificate information

  /api.cgi?cmd=CertificateClear:
    post:
      tags:
        - Network
      summary: Clear certificate
      description: Clear SSL/TLS certificate
      operationId: certificateClear
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [CertificateClear]
      responses:
        '200':
          description: Certificate cleared

  /api.cgi?cmd=GetRtspUrl:
    post:
      tags:
        - Network
      summary: Get RTSP URL
      description: Get RTSP streaming URL for the camera
      operationId: getRtspUrl
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetRtspUrl]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: RTSP URL information

  # ==================== VIDEO INPUT ENDPOINTS ====================

  /api.cgi?cmd=GetImage:
    post:
      tags:
        - Video Input
      summary: Get image settings
      description: |
        Get image quality settings including brightness, contrast, saturation, hue, and sharpness.

        **Parameter Ranges:** All image parameters range from 0-255, with 128 as the default/neutral value.
      operationId: getImage
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetImage]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
            example:
              - cmd: GetImage
                action: 1
                param:
                  channel: 0
      responses:
        '200':
          description: Image settings with ranges
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Image:
                          type: object
                          properties:
                            channel:
                              type: integer
                            bright:
                              type: integer
                              minimum: 0
                              maximum: 255
                              description: Brightness (0-255, default 128)
                            contrast:
                              type: integer
                              minimum: 0
                              maximum: 255
                              description: Contrast (0-255, default 128)
                            saturation:
                              type: integer
                              minimum: 0
                              maximum: 255
                              description: Saturation (0-255, default 128)
                            hue:
                              type: integer
                              minimum: 0
                              maximum: 255
                              description: Hue (0-255, default 128)
                            sharpen:
                              type: integer
                              minimum: 0
                              maximum: 255
                              description: Sharpness (0-255, default 128)

  /api.cgi?cmd=SetImage:
    post:
      tags:
        - Video Input
      summary: Set image settings
      description: |
        Set image quality settings.

        **Parameter Ranges:** All parameters accept values from 0-255.
      operationId: setImage
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetImage]
                  param:
                    type: object
                    properties:
                      Image:
                        type: object
                        properties:
                          channel:
                            type: integer
                            description: Channel number (0-based)
                          bright:
                            type: integer
                            minimum: 0
                            maximum: 255
                          contrast:
                            type: integer
                            minimum: 0
                            maximum: 255
                          saturation:
                            type: integer
                            minimum: 0
                            maximum: 255
                          hue:
                            type: integer
                            minimum: 0
                            maximum: 255
                          sharpen:
                            type: integer
                            minimum: 0
                            maximum: 255
            example:
              - cmd: SetImage
                param:
                  Image:
                    channel: 0
                    bright: 150
                    contrast: 150
                    saturation: 150
                    hue: 150
                    sharpen: 150
      responses:
        '200':
          description: Image settings updated

  /api.cgi?cmd=GetOsd:
    post:
      tags:
        - Video Input
      summary: Get OSD settings
      description: Get On-Screen Display settings (timestamp, camera name overlay)
      operationId: getOsd
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetOsd]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: OSD settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Osd:
                          type: object
                          properties:
                            channel:
                              type: integer
                            osdChannel:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                name:
                                  type: string
                                pos:
                                  type: string
                                  enum: ["Upper Left", "Upper Right", "Lower Left", "Lower Right"]
                            osdTime:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                pos:
                                  type: string
                                  enum: ["Upper Left", "Upper Right", "Lower Left", "Lower Right"]

  /api.cgi?cmd=SetOsd:
    post:
      tags:
        - Video Input
      summary: Set OSD settings
      description: Set On-Screen Display settings
      operationId: setOsd
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetOsd]
                  param:
                    type: object
                    properties:
                      Osd:
                        type: object
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          osdChannel:
                            type: object
                            description: Camera name display settings
                            properties:
                              enable:
                                type: integer
                                enum: [0, 1]
                                description: Camera name display switch
                              name:
                                type: string
                                description: Camera name
                              pos:
                                type: string
                                enum: ["Upper Left", "Upper Right", "Lower Left", "Lower Right"]
                                description: Camera name display position
                          osdTime:
                            type: object
                            description: Time display settings
                            properties:
                              enable:
                                type: integer
                                enum: [0, 1]
                                description: Camera time display switch
                              pos:
                                type: string
                                enum: ["Upper Left", "Upper Right", "Lower Left", "Lower Right"]
                                description: Camera time display position
            example:
              - cmd: SetOsd
                param:
                  Osd:
                    channel: 0
                    osdChannel:
                      enable: 1
                      name: Camera101
                      pos: "Lower Right"
                    osdTime:
                      enable: 1
                      pos: "Upper Right"
      responses:
        '200':
          description: OSD settings updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetIsp:
    post:
      tags:
        - Video Input
      summary: Get ISP settings
      description: Get Image Signal Processor settings (anti-flicker, exposure, day/night mode, etc.)
      operationId: getIsp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetIsp]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: ISP settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Isp:
                          type: object
                          properties:
                            channel:
                              type: integer
                            antiFlicker:
                              type: string
                              enum: ["Outdoor", "50HZ", "60HZ", "Off"]
                            backLight:
                              type: string
                              enum: ["Off", "BackLightControl", "DynamicRangeControl"]
                            blc:
                              type: integer
                            brightness:
                              type: integer
                            contrast:
                              type: integer
                            dayNight:
                              type: string
                              enum: ["Auto", "Color", "Black&White"]
                            drc:
                              type: integer
                            exposure:
                              type: string
                              enum: ["Auto", "LowNoise", "Anti-Smearing", "Manual"]
                            gain:
                              type: object
                            hue:
                              type: integer
                            saturation:
                              type: integer
                            sharpen:
                              type: integer
                            shutter:
                              type: object
                            whiteBalance:
                              type: string
                              enum: ["Auto", "Manual"]

  /api.cgi?cmd=SetIsp:
    post:
      tags:
        - Video Input
      summary: Set ISP settings
      description: |
        Set Image Signal Processor settings.

        **Note:** All image parameters (blc, drc, blueGain, redGain, bright, dark) range from 0-255 with 128 as default.
      operationId: setIsp
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetIsp]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      Isp:
                        type: object
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          antiFlicker:
                            type: string
                            enum: ["Outdoor", "50HZ", "60HZ", "Off"]
                            description: Flicker prevention
                          backLight:
                            type: string
                            enum: ["Off", "BackLightControl", "DynamicRangeControl"]
                            description: Backlight compensation
                          blc:
                            type: integer
                            minimum: 0
                            maximum: 255
                            description: Backlight control level (when backLight is BackLightControl)
                          drc:
                            type: integer
                            minimum: 0
                            maximum: 255
                            description: Dynamic range control level (when backLight is DynamicRangeControl)
                          blueGain:
                            type: integer
                            minimum: 0
                            maximum: 255
                            description: Blue gain (when whiteBalance is Manual)
                          redGain:
                            type: integer
                            minimum: 0
                            maximum: 255
                            description: Red gain (when whiteBalance is Manual)
                          constantFrameRate:
                            type: integer
                            enum: [0, 1]
                            description: Constant frame rate
                          dayNight:
                            type: string
                            enum: ["Auto", "Color", "Black&White"]
                            description: Day & Night mode
                          exposure:
                            type: string
                            enum: ["Auto", "LowNoise", "Anti-Smearing", "Manual"]
                            description: Exposure mode
                          gain:
                            type: object
                            description: Gain settings (when exposure is LowNoise or Manual)
                            properties:
                              min:
                                type: integer
                              max:
                                type: integer
                          shutter:
                            type: object
                            description: Shutter settings (when exposure is Anti-Smearing or Manual)
                            properties:
                              min:
                                type: integer
                              max:
                                type: integer
                          whiteBalance:
                            type: string
                            enum: ["Auto", "Manual"]
                            description: White balance
                          mirroring:
                            type: integer
                            enum: [0, 1]
                            description: Mirror image
                          rotation:
                            type: integer
                            enum: [0, 90, 270]
                            description: Rotation angle
                          nr3d:
                            type: integer
                            enum: [0, 1]
                            description: 3D noise reduction
            example:
              - cmd: SetIsp
                action: 0
                param:
                  Isp:
                    channel: 0
                    antiFlicker: "Off"
                    backLight: "Off"
                    constantFrameRate: 1
                    blc: 128
                    blueGain: 128
                    dayNight: Auto
                    drc: 128
                    exposure: Auto
                    gain:
                      max: 62
                      min: 1
                    mirroring: 0
                    nr3d: 1
                    redGain: 128
                    rotation: 0
                    shutter:
                      max: 125
                      min: 0
                    whiteBalance: Auto
      responses:
        '200':
          description: ISP settings updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetMask:
    post:
      tags:
        - Video Input
      summary: Get privacy mask settings
      description: Get privacy zone/mask configuration
      operationId: getMask
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetMask]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Privacy mask settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Mask:
                          type: object
                          properties:
                            channel:
                              type: integer
                            area:
                              type: array
                              description: Privacy mask areas
                              items:
                                type: object

  /api.cgi?cmd=SetMask:
    post:
      tags:
        - Video Input
      summary: Set privacy mask settings
      description: Set privacy zone/mask configuration
      operationId: setMask
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetMask]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      Mask:
                        type: object
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          enable:
                            type: integer
                            enum: [0, 1]
                            description: Video mask switch
                          area:
                            type: array
                            description: Array of privacy mask areas (up to 4 areas)
                            items:
                              type: object
                              properties:
                                screen:
                                  type: object
                                  description: Screen dimensions
                                  properties:
                                    height:
                                      type: integer
                                      description: Screen height
                                    width:
                                      type: integer
                                      description: Screen width
                                block:
                                  type: object
                                  description: Mask block coordinates and size
                                  properties:
                                    x:
                                      type: integer
                                      description: Left upper X axis coordinate
                                    y:
                                      type: integer
                                      description: Left upper Y axis coordinate
                                    width:
                                      type: integer
                                      description: Block width
                                    height:
                                      type: integer
                                      description: Block height
            example:
              - cmd: SetMask
                action: 0
                param:
                  Mask:
                    channel: 0
                    enable: 1
                    area:
                      - screen:
                          height: 720
                          width: 1280
                        block:
                          x: 110
                          y: 95
                          width: 36
                          height: 166
                      - screen:
                          height: 720
                          width: 1280
                        block:
                          x: 251
                          y: 100
                          width: 54
                          height: 175
      responses:
        '200':
          description: Privacy mask settings updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetCrop:
    post:
      tags:
        - Video Input
      summary: Get crop settings
      description: Get video crop/zoom configuration
      operationId: getCrop
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetCrop]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Crop settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Crop:
                          type: object
                          properties:
                            channel:
                              type: integer
                            screenWidth:
                              type: integer
                            screenHeight:
                              type: integer
                            cropWidth:
                              type: integer
                            cropHeight:
                              type: integer
                            topLeftX:
                              type: integer
                            topLeftY:
                              type: integer

  /api.cgi?cmd=SetCrop:
    post:
      tags:
        - Video Input
      summary: Set crop settings
      description: Set video crop/zoom configuration
      operationId: setCrop
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetCrop]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      Crop:
                        type: object
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number (NVR)
                          screenWidth:
                            type: integer
                            description: Screen width
                          screenHeight:
                            type: integer
                            description: Screen height
                          cropWidth:
                            type: integer
                            description: Width of crop area
                          cropHeight:
                            type: integer
                            description: Height of crop area
                          topLeftX:
                            type: integer
                            description: Distance between upper left corner of crop area and left boundary
                          topLeftY:
                            type: integer
                            description: Distance between upper left corner of crop area and upper boundary
            example:
              - cmd: SetCrop
                action: 0
                param:
                  Crop:
                    channel: 0
                    screenWidth: 2560
                    screenHeight: 1920
                    cropWidth: 640
                    cropHeight: 480
                    topLeftX: 960
                    topLeftY: 720
      responses:
        '200':
          description: Crop settings updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetStitch:
    post:
      tags:
        - Video Input
      summary: Get stitch settings
      description: Get video stitching configuration (for multi-lens cameras)
      operationId: getStitch
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetStitch]
      responses:
        '200':
          description: Stitch settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        stitch:
                          type: object
                          properties:
                            distance:
                              type: number
                            stitchXMove:
                              type: integer
                            stitchYMove:
                              type: integer

  /api.cgi?cmd=SetStitch:
    post:
      tags:
        - Video Input
      summary: Set stitch settings
      description: |
        Set video stitching configuration for multi-lens cameras.

        **Note:** This command is used for "stitching binocular" IPC to adjust the stitching picture.
      operationId: setStitch
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetStitch]
                  param:
                    type: object
                    properties:
                      stitch:
                        type: object
                        required:
                          - distance
                          - stitchXMove
                          - stitchYMove
                        properties:
                          distance:
                            type: number
                            description: Distance between images
                          stitchXMove:
                            type: integer
                            description: Adjust pixels horizontally
                          stitchYMove:
                            type: integer
                            description: Adjust pixels vertically
            example:
              - cmd: setStitch
                param:
                  stitch:
                    distance: 8.1
                    stitchXMove: 5
                    stitchYMove: 3
      responses:
        '200':
          description: Stitch settings updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  # ==================== ENCODING ENDPOINTS ====================

  /api.cgi?cmd=GetEnc:
    post:
      tags:
        - Encoding
      summary: Get encoding configuration
      description: |
        Get video encoding settings including codec, resolution, bitrate, framerate, and GOP.

        **Important Notes:**
        - Use `action: 1` to get available options (resolutions, bitrates, framerates) and current values
        - Use `action: 0` to get only current values
        - The `range` field contains arrays of supported resolutions, bitrates, and framerates
        - Different resolutions may have different available bitrate and framerate options
        - The response includes `mainStream`, `subStream`, and optionally `extStream` configurations

        **Common Resolutions:**
        - 4K: 3840*2160
        - 2K: 2560*1440
        - 3MP: 2304*1296
        - 1080p: 1920*1080
        - 720p: 1280*720
        - VGA: 640*480
        - Sub stream: 640*360

        **Typical Bitrates (kbps):**
        - Main stream: 1024, 1536, 2048, 3072, 4096, 5120, 6144, 7168, 8192
        - Sub stream: 64, 128, 160, 192, 256, 384, 512

        **Typical Framerates (fps):**
        - Main stream: 2, 4, 6, 8, 10, 12, 15, 16, 18, 20, 22, 25
        - Sub stream: 4, 7, 10, 15
      operationId: getEnc
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetEnc]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
            example:
              - cmd: GetEnc
                action: 1
                param:
                  channel: 0
      responses:
        '200':
          description: Encoding configuration including main stream and sub stream settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: GetEnc
                    code:
                      type: integer
                      example: 0
                    initial:
                      type: object
                      description: Initial/default values (when action=1)
                      properties:
                        Enc:
                          type: object
                          properties:
                            audio:
                              type: integer
                              enum: [0, 1]
                            channel:
                              type: integer
                            mainStream:
                              $ref: '#/components/schemas/StreamConfig'
                            subStream:
                              $ref: '#/components/schemas/StreamConfig'
                    range:
                      type: object
                      description: |
                        Available options for each resolution (when action=1).
                        Contains array of configuration objects, one for each supported resolution.
                        Each object includes arrays of available bitrates, framerates, and other options.
                      properties:
                        Enc:
                          type: array
                          items:
                            type: object
                            properties:
                              audio:
                                type: string
                                example: "boolean"
                              chnBit:
                                type: integer
                                description: Channel bit mask
                              mainStream:
                                type: object
                                properties:
                                  bitRate:
                                    type: array
                                    items:
                                      type: integer
                                    description: Available bitrates in kbps
                                    example: [4096, 5120, 6144, 7168, 8192]
                                  frameRate:
                                    type: array
                                    items:
                                      type: integer
                                    description: Available framerates in fps
                                    example: [25, 22, 20, 18, 16, 15, 12, 10, 8, 6, 4, 2]
                                  gop:
                                    type: object
                                    properties:
                                      min:
                                        type: integer
                                      max:
                                        type: integer
                                  profile:
                                    type: array
                                    items:
                                      type: string
                                    example: ["Base", "Main", "High"]
                                  size:
                                    type: string
                                    example: "3840*2160"
                                  vType:
                                    type: string
                                    example: "h265"
                                  width:
                                    type: integer
                                  height:
                                    type: integer
                                  default:
                                    type: object
                                    description: Default values for this resolution
                                    properties:
                                      bitRate:
                                        type: integer
                                      frameRate:
                                        type: integer
                                      gop:
                                        type: integer
                              subStream:
                                type: object
                                description: Similar structure to mainStream
                    value:
                      type: object
                      description: Current encoding configuration
                      properties:
                        Enc:
                          type: object
                          properties:
                            audio:
                              type: integer
                              enum: [0, 1]
                              description: "0: audio disabled, 1: audio enabled"
                            channel:
                              type: integer
                            mainStream:
                              $ref: '#/components/schemas/StreamConfig'
                            subStream:
                              $ref: '#/components/schemas/StreamConfig'

  /api.cgi?cmd=SetEnc:
    post:
      tags:
        - Encoding
      summary: Set encoding configuration
      description: |
        Set video encoding settings for main and sub streams.

        **Important Notes:**
        - Use GetEnc with `action: 1` first to see available options for your camera model
        - Not all resolutions support all bitrates and framerates
        - Changing resolution may require compatible bitrate and framerate values
        - GOP (Group of Pictures) typically ranges from 1-4
        - Profile options: Base, Main, High (High provides better quality)
      operationId: setEnc
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetEnc]
                  param:
                    type: object
                    properties:
                      Enc:
                        type: object
                        properties:
                          channel:
                            type: integer
                            description: Channel number (0-based)
                          audio:
                            type: integer
                            enum: [0, 1]
                            description: "0: disable audio, 1: enable audio"
                          mainStream:
                            $ref: '#/components/schemas/StreamConfig'
                          subStream:
                            $ref: '#/components/schemas/StreamConfig'
            example:
              - cmd: SetEnc
                param:
                  Enc:
                    channel: 0
                    audio: 1
                    mainStream:
                      vType: h265
                      size: "3840*2160"
                      width: 3840
                      height: 2160
                      frameRate: 25
                      bitRate: 6144
                      gop: 2
                      profile: High
                    subStream:
                      vType: h264
                      size: "640*360"
                      width: 640
                      height: 360
                      frameRate: 10
                      bitRate: 256
                      gop: 4
                      profile: High
      responses:
        '200':
          description: Encoding configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: SetEnc
                    code:
                      type: integer
                      example: 0
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          example: 200

  # ==================== RECORD ENDPOINTS ====================

  /api.cgi?cmd=GetRec:
    post:
      tags:
        - Record
      summary: Get recording configuration
      description: |
        Get recording schedule and settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `GetRecV20` instead for enhanced features.

        **Model Note:** This command supports model 52X only.
      operationId: getRec
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetRec]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
      responses:
        '200':
          description: Recording configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Rec:
                          type: object
                          properties:
                            channel:
                              type: integer
                            enable:
                              type: integer
                              enum: [0, 1]
                            overwrite:
                              type: integer
                              enum: [0, 1]
                            preRecord:
                              type: integer
                              enum: [0, 1]
                            schedule:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                table:
                                  type: string
                                  description: 168-character schedule string

  /api.cgi?cmd=SetRec:
    post:
      tags:
        - Record
      summary: Set recording configuration
      description: |
        Set recording schedule and settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `SetRecV20` instead for enhanced features.

        **Schedule Table Format:** 168-character string representing 7 days × 24 hours (1=record, 0=no record).
      operationId: setRec
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetRec]
                  param:
                    type: object
                    properties:
                      Rec:
                        type: object
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          overwrite:
                            type: integer
                            enum: [0, 1]
                            description: Overwrite oldest recordings when disk is full
                          postRec:
                            type: string
                            enum: ["30 Seconds", "1 Minute", "2 Minutes", "3 Minutes", "4 Minutes", "5 Minutes"]
                            description: Post-recording duration
                          preRec:
                            type: integer
                            enum: [0, 1]
                            description: Pre-recording enable
                          schedule:
                            type: object
                            description: Recording schedule
                            properties:
                              enable:
                                type: integer
                                enum: [0, 1]
                                description: Enable schedule
                              table:
                                type: string
                                minLength: 168
                                maxLength: 168
                                description: 168-character schedule table (7 days × 24 hours)
            example:
              - cmd: SetRec
                param:
                  Rec:
                    channel: 0
                    overwrite: 1
                    postRec: "30 Seconds"
                    preRec: 1
                    schedule:
                      enable: 1
                      table: "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111"
      responses:
        '200':
          description: Recording configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetRecV20:
    post:
      tags:
        - Record
      summary: Get recording configuration (v2.0)
      description: |
        Get recording schedule and settings (version 2.0 with enhanced features).

        **Version Note:** Use this command when `scheduleVersion.ver = 1` in the capability set (from GetAbility).
      operationId: getRecV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetRecV20]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Recording configuration (v2.0)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Rec:
                          type: object
                          properties:
                            channel:
                              type: integer
                            enable:
                              type: integer
                              enum: [0, 1]
                            overwrite:
                              type: integer
                              enum: [0, 1]
                            preRecord:
                              type: integer
                              enum: [0, 1]
                            schedule:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                table:
                                  type: object
                                  description: Schedule tables for different alarm types
                                  properties:
                                    MD:
                                      type: string
                                      description: Motion detection schedule (168 chars)
                                    TIMING:
                                      type: string
                                      description: Timing schedule (168 chars)
                                    AI_PEOPLE:
                                      type: string
                                      description: AI people detection schedule (168 chars)
                                    AI_VEHICLE:
                                      type: string
                                      description: AI vehicle detection schedule (168 chars)
                                    AI_DOG_CAT:
                                      type: string
                                      description: AI dog/cat detection schedule (168 chars)

  /api.cgi?cmd=SetRecV20:
    post:
      tags:
        - Record
      summary: Set recording configuration (v2.0)
      description: |
        Set recording schedule and settings (version 2.0).

        **Version Note:** Use this command when `scheduleVersion.ver = 1` in the capability set.

        **Schedule Table Format:** 168-character string for each alarm type (MD, TIMING, AI_PEOPLE, AI_VEHICLE, AI_DOG_CAT).
      operationId: setRecV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetRecV20]
                  param:
                    type: object
                    properties:
                      Rec:
                        type: object
                        properties:
                          overwrite:
                            type: integer
                            enum: [0, 1]
                            description: Overwrite oldest recordings when disk is full
                          postRec:
                            type: string
                            enum: ["30 Seconds", "1 Minute", "2 Minutes", "3 Minutes", "4 Minutes", "5 Minutes"]
                            description: Post-recording duration
                          preRec:
                            type: integer
                            enum: [0, 1]
                            description: Pre-recording enable
                          saveDay:
                            type: integer
                            description: Number of days to save recordings
                          schedule:
                            type: object
                            description: Recording schedule with alarm type tables
                            properties:
                              enable:
                                type: integer
                                enum: [0, 1]
                                description: Enable schedule
                              channel:
                                type: integer
                                description: Channel number
                              table:
                                type: object
                                description: Schedule tables for different alarm types
                                properties:
                                  MD:
                                    type: string
                                    minLength: 168
                                    maxLength: 168
                                    description: Motion detection schedule (168 chars)
                                  TIMING:
                                    type: string
                                    minLength: 168
                                    maxLength: 168
                                    description: Timing/continuous recording schedule (168 chars)
                                  AI_PEOPLE:
                                    type: string
                                    minLength: 168
                                    maxLength: 168
                                    description: AI people detection schedule (168 chars)
                                  AI_VEHICLE:
                                    type: string
                                    minLength: 168
                                    maxLength: 168
                                    description: AI vehicle detection schedule (168 chars)
                                  AI_DOG_CAT:
                                    type: string
                                    minLength: 168
                                    maxLength: 168
                                    description: AI dog/cat detection schedule (168 chars)
            example:
              - cmd: SetRecV20
                param:
                  Rec:
                    overwrite: 1
                    postRec: "30 Seconds"
                    preRec: 1
                    saveDay: 30
                    schedule:
                      enable: 1
                      channel: 0
                      table:
                        MD: "100111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111100"
                        TIMING: "101111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111"
      responses:
        '200':
          description: Recording configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=Search:
    post:
      tags:
        - Record
      summary: Search recordings
      description: |
        Search for recorded video files by time range.

        **Important Warning:** Searching a big amount of files might lead to **searching timeout**.
        Consider using smaller time ranges for better performance.
      operationId: searchRecordings
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [Search]
                  param:
                    type: object
                    properties:
                      Search:
                        type: object
                        properties:
                          channel:
                            type: integer
                            description: Channel number (0-based)
                          streamType:
                            type: string
                            enum: [main, sub, ext]
                            description: Stream type to search
                          StartTime:
                            type: object
                            description: Search start time
                            properties:
                              year:
                                type: integer
                              mon:
                                type: integer
                                minimum: 1
                                maximum: 12
                              day:
                                type: integer
                                minimum: 1
                                maximum: 31
                              hour:
                                type: integer
                                minimum: 0
                                maximum: 23
                              min:
                                type: integer
                                minimum: 0
                                maximum: 59
                              sec:
                                type: integer
                                minimum: 0
                                maximum: 59
                          EndTime:
                            type: object
                            description: Search end time
                            properties:
                              year:
                                type: integer
                              mon:
                                type: integer
                                minimum: 1
                                maximum: 12
                              day:
                                type: integer
                                minimum: 1
                                maximum: 31
                              hour:
                                type: integer
                                minimum: 0
                                maximum: 23
                              min:
                                type: integer
                                minimum: 0
                                maximum: 59
                              sec:
                                type: integer
                                minimum: 0
                                maximum: 59
            example:
              - cmd: Search
                param:
                  Search:
                    channel: 0
                    streamType: main
                    StartTime:
                      year: 2023
                      mon: 6
                      day: 1
                      hour: 0
                      min: 0
                      sec: 0
                    EndTime:
                      year: 2023
                      mon: 6
                      day: 1
                      hour: 23
                      min: 59
                      sec: 59
      responses:
        '200':
          description: List of recording files

  /api.cgi?cmd=Download:
    post:
      tags:
        - Record
      summary: Download recording
      description: |
        Download a recorded video file.

        **Special URL Format (GET request):**
        ```
        https://IPC_IP/cgi-bin/api.cgi?cmd=Download&source=SOURCE_FILE&output=OUTPUT_FILE&token=TOKEN
        ```

        **Parameters:**
        - **source** (required): Path to the source file (e.g., `Mp4Record/2020-12-21/RecM01_20201221_121551_121553_6D28808_2240A8.mp4`)
        - **output** (required): Output filename for download

        **Response:** Binary video file with Content-Type: application/octet-stream
      operationId: downloadRecording
      security:
        - tokenAuth: []
        - basicAuth: []
      parameters:
        - name: source
          in: query
          required: true
          schema:
            type: string
          description: Path to the source recording file
        - name: output
          in: query
          required: true
          schema:
            type: string
          description: Output filename for the download
      responses:
        '200':
          description: Video file download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /api.cgi?cmd=Snap:
    post:
      tags:
        - Record
      summary: Take snapshot
      description: |
        Capture a still image from the camera.

        **Special URL Format (GET request):**
        ```
        https://IPC_IP/cgi-bin/api.cgi?cmd=Snap&channel=0&rs=RANDOM_STRING&token=TOKEN
        ```

        **Parameters:**
        - **channel** (required): Channel number (0-based)
        - **rs** (required): Random string with fixed length to prevent browser caching

        **Response:** JPEG image with Content-Type: image/jpeg
      operationId: snap
      security:
        - tokenAuth: []
        - basicAuth: []
      parameters:
        - name: channel
          in: query
          required: true
          schema:
            type: integer
          description: Channel number (0-based)
        - name: rs
          in: query
          required: true
          schema:
            type: string
          description: Random string to prevent browser caching (e.g., "flsYJfZgM6RTB_os")
      responses:
        '200':
          description: Snapshot image
          content:
            image/jpeg:
              schema:
                type: string
                format: binary

  /api.cgi?cmd=Playback:
    post:
      tags:
        - Record
      summary: Playback recording
      description: |
        Stream playback of a recorded video.

        **Special URL Format (GET request):**
        ```
        https://IPC_IP/cgi-bin/api.cgi?cmd=Playback&source=SOURCE_FILE&output=OUTPUT_FILE&token=TOKEN
        ```

        **Parameters:**
        - **source** (required): Path to the source file (e.g., `Mp4Record/2020-12-22/RecM01_20201222_075939_080140_6D28808_1A468F9.mp4`)
        - **output** (required): Output path/filename

        **Response:** Video stream with Content-Type: application/octet-stream
      operationId: playback
      security:
        - tokenAuth: []
        - basicAuth: []
      parameters:
        - name: source
          in: query
          required: true
          schema:
            type: string
          description: Path to the source recording file
        - name: output
          in: query
          required: true
          schema:
            type: string
          description: Output path/filename
      responses:
        '200':
          description: Video stream
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /api.cgi?cmd=NvrDownload:
    post:
      tags:
        - Record
      summary: Download NVR recording
      description: Download recording from NVR with optional stream type selection
      operationId: nvrDownload
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Video file download

  # ==================== PTZ ENDPOINTS ====================

  /api.cgi?cmd=GetPtzPreset:
    post:
      tags:
        - PTZ
      summary: Get PTZ presets
      description: Get Pan-Tilt-Zoom preset positions
      operationId: getPtzPreset
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPtzPreset]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: PTZ preset positions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        PtzPreset:
                          type: array
                          description: List of preset positions
                          items:
                            type: object
                            properties:
                              enable:
                                type: integer
                                enum: [0, 1]
                              id:
                                type: integer
                                minimum: 1
                                maximum: 64
                              name:
                                type: string

  /api.cgi?cmd=SetPtzPreset:
    post:
      tags:
        - PTZ
      summary: Set PTZ preset
      description: Set or call a PTZ preset position
      operationId: setPtzPreset
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetPtzPreset]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      PtzPreset:
                        type: object
                        required:
                          - channel
                          - id
                          - name
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          enable:
                            type: integer
                            enum: [0, 1]
                            description: 1=on, 0=off. If not present, only name can be revised
                          id:
                            type: integer
                            minimum: 1
                            maximum: 64
                            description: ID number of preset (range 1-64)
                          name:
                            type: string
                            minLength: 1
                            maxLength: 31
                            description: Name of preset (1-31 characters)
            example:
              - cmd: SetPtzPreset
                action: 0
                param:
                  PtzPreset:
                    channel: 0
                    enable: 1
                    id: 1
                    name: pos1
      responses:
        '200':
          description: PTZ preset set
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetPtzPatrol:
    post:
      tags:
        - PTZ
      summary: Get PTZ patrol
      description: Get PTZ patrol/tour configuration
      operationId: getPtzPatrol
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPtzPatrol]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: PTZ patrol configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        PtzPatrol:
                          type: object
                          properties:
                            enable:
                              type: integer
                              enum: [0, 1]
                            preset:
                              type: array
                              description: List of presets in patrol (max 16)
                              items:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                  dwellTime:
                                    type: integer
                                  speed:
                                    type: integer

  /api.cgi?cmd=SetPtzPatrol:
    post:
      tags:
        - PTZ
      summary: Set PTZ patrol
      description: |
        Set PTZ patrol/tour configuration.

        **Note:** Supports up to 16 presets per patrol.
      operationId: setPtzPatrol
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetPtzPatrol]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      PtzPatrol:
                        type: object
                        required:
                          - channel
                          - enable
                          - id
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          enable:
                            type: integer
                            enum: [0, 1]
                            description: Whether to enable the preset
                          id:
                            type: integer
                            description: ID number of patrol
                          running:
                            type: integer
                            enum: [0, 1]
                            description: Running status
                          name:
                            type: string
                            description: Name of patrol
                          preset:
                            type: array
                            description: Array of presets (up to 16)
                            items:
                              type: object
                              required:
                                - id
                                - dwellTime
                                - speed
                              properties:
                                id:
                                  type: integer
                                  minimum: 1
                                  maximum: 64
                                  description: ID number of preset (range 1-64)
                                dwellTime:
                                  type: integer
                                  description: Patrol time (dwell time at preset)
                                speed:
                                  type: integer
                                  description: Patrol speed
            example:
              - cmd: SetPtzPatrol
                action: 0
                param:
                  PtzPatrol:
                    channel: 0
                    enable: 1
                    id: 1
                    running: 0
                    name: hello
                    preset:
                      - dwellTime: 3
                        id: 1
                        speed: 10
                      - dwellTime: 4
                        id: 2
                        speed: 20
      responses:
        '200':
          description: PTZ patrol configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=PtzCtrl:
    post:
      tags:
        - PTZ
      summary: PTZ control
      description: |
        Control PTZ (Pan-Tilt-Zoom) movement and operations.

        **Available Operations:**
        - **Stop**: Stop PTZ movement
        - **Left**: Turn left at specified speed
        - **Right**: Turn right at specified speed
        - **Up**: Turn up at specified speed
        - **Down**: Turn down at specified speed
        - **LeftUp**: Turn diagonally left-up at specified speed
        - **LeftDown**: Turn diagonally left-down at specified speed
        - **RightUp**: Turn diagonally right-up at specified speed
        - **RightDown**: Turn diagonally right-down at specified speed
        - **ZoomInc**: Zoom out at specified speed
        - **ZoomDec**: Zoom in at specified speed
        - **FocusInc**: Focus forwards at specified speed
        - **FocusDec**: Focus backwards at specified speed
        - **IrisInc**: Iris enlarge at specified speed
        - **IrisDec**: Iris shrink at specified speed
        - **Auto**: Auto pan at specified speed
        - **ToPos**: Move to a specific preset position
        - **StartPatrol**: Start patrol at specified speed
        - **StopPatrol**: Stop patrol

        **Notes:**
        - Some parameters may not be needed for certain operations (set to 0 if unused)
        - Speed typically ranges from 1-64
        - `id` parameter is required for ToPos and StartPatrol operations
      operationId: ptzCtrl
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [PtzCtrl]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: IPC channel number (0-based)
                      op:
                        type: string
                        enum: [Stop, Left, Right, Up, Down, LeftUp, LeftDown, RightUp, RightDown, ZoomInc, ZoomDec, FocusInc, FocusDec, IrisInc, IrisDec, Auto, ToPos, StartPatrol, StopPatrol]
                        description: PTZ operation to perform
                      speed:
                        type: integer
                        minimum: 1
                        maximum: 64
                        description: PTZ running speed (optional for some operations)
                      id:
                        type: integer
                        description: Preset ID (for ToPos) or Patrol ID (for StartPatrol)
            examples:
              moveLeft:
                summary: Move PTZ left
                value:
                  - cmd: PtzCtrl
                    param:
                      channel: 0
                      op: Left
                      speed: 32
              stopMovement:
                summary: Stop PTZ movement
                value:
                  - cmd: PtzCtrl
                    param:
                      channel: 0
                      op: Stop
              gotoPreset:
                summary: Move to preset position
                value:
                  - cmd: PtzCtrl
                    param:
                      channel: 0
                      op: ToPos
                      id: 1
                      speed: 32
              startPatrol:
                summary: Start patrol
                value:
                  - cmd: PtzCtrl
                    param:
                      channel: 0
                      op: StartPatrol
                      id: 1
                      speed: 32
      responses:
        '200':
          description: PTZ command executed
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: PtzCtrl
                    code:
                      type: integer
                      example: 0
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          example: 200

  /api.cgi?cmd=GetPtzSerial:
    post:
      tags:
        - PTZ
      summary: Get PTZ serial configuration
      description: Get PTZ RS485 serial port configuration
      operationId: getPtzSerial
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPtzSerial]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: PTZ serial configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        PtzSerial:
                          type: object
                          properties:
                            baudRate:
                              type: integer
                            dataBits:
                              type: string
                              enum: ["CS8", "CS7", "CS6", "CS5"]
                            flowCtrl:
                              type: string
                              enum: ["none", "hard", "xon", "xoff"]
                            parity:
                              type: string
                              enum: ["none", "odd", "even"]
                            protocol:
                              type: string
                              enum: ["PELCO_D", "PELCO_P"]
                            stopBits:
                              type: integer

  /api.cgi?cmd=SetPtzSerial:
    post:
      tags:
        - PTZ
      summary: Set PTZ serial configuration
      description: Set PTZ RS485 serial port configuration
      operationId: setPtzSerial
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetPtzSerial]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      PtzSerial:
                        type: object
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: Channel number
                          baudRate:
                            type: integer
                            description: Baud rate of the serial in PTZ
                          dataBit:
                            type: string
                            enum: ["CS8", "CS7", "CS6", "CS5"]
                            description: Data bit of the serial in PTZ
                          stopBit:
                            type: integer
                            enum: [1, 2]
                            description: Stop bit of the serial in PTZ
                          parity:
                            type: string
                            enum: ["none", "odd", "even"]
                            description: Parity of the serial in PTZ
                          flowCtrl:
                            type: string
                            enum: ["none", "hard", "xon", "xoff"]
                            description: Flow control of the serial in PTZ
                          ctrlProtocol:
                            type: string
                            enum: ["PELCO_D", "PELCO_P"]
                            description: Control protocol of the serial in PTZ
                          ctrlAddr:
                            type: integer
                            description: Control address of the serial in PTZ (default = channel + 1)
            example:
              - cmd: SetPtzSerial
                action: 0
                param:
                  PtzSerial:
                    channel: 0
                    baudRate: 9600
                    dataBit: CS6
                    stopBit: 2
                    parity: odd
                    flowCtrl: hard
                    crtlProtocol: PELCO_P
                    ctrlAddr: 2
      responses:
        '200':
          description: PTZ serial configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetPtzTattern:
    post:
      tags:
        - PTZ
      summary: Get PTZ pattern
      description: Get PTZ pattern/track configuration
      operationId: getPtzTattern
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPtzTattern]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: PTZ pattern configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        PtzTattern:
                          type: object
                          properties:
                            enable:
                              type: integer
                              enum: [0, 1]
                            id:
                              type: integer
                              minimum: 1
                              maximum: 6
                              description: Track ID

  /api.cgi?cmd=SetPtzTattern:
    post:
      tags:
        - PTZ
      summary: Set PTZ pattern
      description: |
        Set PTZ pattern/track configuration.

        **Note:** Track ID range is 1-6.
      operationId: setPtzTattern
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetPtzTattern]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      PtzTattern:
                        type: object
                        required:
                          - channel
                          - track
                        properties:
                          channel:
                            type: integer
                            description: Channel number
                          track:
                            type: array
                            description: Array of tracks (up to 6)
                            items:
                              type: object
                              required:
                                - id
                              properties:
                                id:
                                  type: integer
                                  minimum: 1
                                  maximum: 6
                                  description: ID number of the track (range 1-6)
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                  description: Track switch (1=enabled, 0=disabled)
                                running:
                                  type: integer
                                  enum: [0, 1]
                                  description: Whether running or not
                                name:
                                  type: string
                                  description: Name of the track
            example:
              - cmd: SetPtzTattern
                action: 0
                param:
                  PtzTattern:
                    channel: 0
                    track:
                      - id: 1
                        enable: 0
                        running: 0
                        name: track1
                      - id: 2
                        enable: 0
                        running: 0
                        name: track2
      responses:
        '200':
          description: PTZ pattern configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetAutoFocus:
    post:
      tags:
        - PTZ
      summary: Get auto focus configuration
      description: Get auto focus settings
      operationId: getAutoFocus
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAutoFocus]
                  action:
                    type: integer
                    enum: [0, 1]
      responses:
        '200':
          description: Auto focus configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        AutoFocus:
                          type: object
                          properties:
                            channel:
                              type: integer
                            disable:
                              type: integer
                              enum: [0, 1]
                              description: 0=auto focus enabled, 1=disabled

  /api.cgi?cmd=SetAutoFocus:
    post:
      tags:
        - PTZ
      summary: Set auto focus configuration
      description: Set auto focus settings
      operationId: setAutoFocus
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetAutoFocus]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      AutoFocus:
                        type: object
                        required:
                          - channel
                          - disable
                        properties:
                          channel:
                            type: integer
                            description: Channel number
                          disable:
                            type: integer
                            enum: [0, 1]
                            description: Forbid autofocus of PTZ (1=forbid, 0=enable)
            example:
              - cmd: SetAutoFocus
                action: 0
                param:
                  AutoFocus:
                    channel: 0
                    disable: 1
      responses:
        '200':
          description: Auto focus configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetZoomFocus:
    post:
      tags:
        - PTZ
      summary: Get zoom focus position
      description: Get current zoom and focus position
      operationId: getZoomFocus
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetZoomFocus]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Zoom focus position
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        ZoomFocus:
                          type: object
                          properties:
                            channel:
                              type: integer
                            zoom:
                              type: object
                              properties:
                                pos:
                                  type: integer
                                  description: Zoom position
                            focus:
                              type: object
                              properties:
                                pos:
                                  type: integer
                                  description: Focus position

  /api.cgi?cmd=StartZoomFocus:
    post:
      tags:
        - PTZ
      summary: Start zoom focus
      description: Start zoom or focus operation
      operationId: startZoomFocus
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [StartZoomFocus]
                  param:
                    type: object
                    properties:
                      ZoomFocus:
                        type: object
                        properties:
                          channel:
                            type: integer
                          op:
                            type: string
                            enum: [ZoomInc, ZoomDec, FocusInc, FocusDec]
                          pos:
                            type: integer
      responses:
        '200':
          description: Zoom focus operation started

  /api.cgi?cmd=GetPtzGuard:
    post:
      tags:
        - PTZ
      summary: Get PTZ guard configuration
      description: Get PTZ guard/home position configuration
      operationId: getPtzGuard
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPtzGuard]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: PTZ guard configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        PtzGuard:
                          type: object
                          properties:
                            channel:
                              type: integer
                            cmdStr:
                              type: string
                              description: Command string
                            timeout:
                              type: integer
                              description: Timeout in seconds (currently only 60)

  /api.cgi?cmd=SetPtzGuard:
    post:
      tags:
        - PTZ
      summary: Set PTZ guard configuration
      description: |
        Set PTZ guard/home position configuration.

        **Note:** Timeout can only be 60 seconds currently.
      operationId: setPtzGuard
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetPtzGuard]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      PtzGuard:
                        type: object
                        required:
                          - channel
                          - cmdStr
                        properties:
                          channel:
                            type: integer
                            description: Channel number
                          cmdStr:
                            type: string
                            enum: ["setPos", "toPos"]
                            description: Command (setPos=set this pos as guard, toPos=go to the guard)
                          benable:
                            type: integer
                            enum: [0, 1]
                            description: Whether automatically return to guard position
                          bexistPos:
                            type: integer
                            enum: [0, 1]
                            description: Whether guard position exists
                          timeout:
                            type: integer
                            description: Time of automatically return to guard position (currently only 60 seconds)
                          bSaveCurrentPos:
                            type: integer
                            enum: [0, 1]
                            description: Whether to set this pos as guard
            example:
              - cmd: SetPtzGuard
                action: 0
                param:
                  PtzGuard:
                    channel: 0
                    cmdStr: ""
                    benable: 1
                    bexistPos: 1
                    timeout: 60
                    bSaveCurrentPos: 1
      responses:
        '200':
          description: PTZ guard configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetPtzCheckState:
    post:
      tags:
        - PTZ
      summary: Get PTZ check state
      description: Get PTZ calibration check state
      operationId: getPtzCheckState
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPtzCheckState]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: PTZ check state
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        status:
                          type: integer
                          description: Check state status

  /api.cgi?cmd=PtzCheck:
    post:
      tags:
        - PTZ
      summary: PTZ calibration check
      description: Perform PTZ calibration check
      operationId: ptzCheck
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [PtzCheck]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: PTZ check initiated

  # ==================== ALARM ENDPOINTS ====================

  /api.cgi?cmd=GetAlarm:
    post:
      tags:
        - Alarm
      summary: Get alarm configuration
      description: |
        Get general alarm configuration (IO, RF alarms).

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `GetMdAlarm` for motion detection alarms instead.

        **Note:** Alarm type "md" (motion detection) is supported.
      operationId: getAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAlarm]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
      responses:
        '200':
          description: Alarm configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        Alarm:
                          type: object
                          properties:
                            channel:
                              type: integer
                            type:
                              type: string
                              description: Alarm type (e.g., "md" for motion detection)
                            enable:
                              type: integer
                              enum: [0, 1]
                            scope:
                              type: object
                              properties:
                                cols:
                                  type: integer
                                rows:
                                  type: integer
                                table:
                                  type: string
                            sens:
                              type: array
                              description: Time-based sensitivity settings
                              items:
                                type: object
                                properties:
                                  beginHour:
                                    type: integer
                                  beginMin:
                                    type: integer
                                  endHour:
                                    type: integer
                                  endMin:
                                    type: integer
                                  sensitivity:
                                    type: integer

  /api.cgi?cmd=SetAlarm:
    post:
      tags:
        - Alarm
      summary: Set alarm configuration
      description: |
        Set general alarm configuration.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `SetMdAlarm` for motion detection alarms instead.

        **Scope Table:** 4800-character string for 80×60 grid (1=detect, 0=no detect).
      operationId: setAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetAlarm]
                  param:
                    type: object
                    properties:
                      Alarm:
                        type: object
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          scope:
                            type: object
                            description: Motion detection scope/area
                            properties:
                              cols:
                                type: integer
                                description: Number of columns (typically 80)
                              rows:
                                type: integer
                                description: Number of rows (typically 60)
                              table:
                                type: string
                                description: Detection grid (cols × rows characters, 1=detect, 0=no detect)
                          sens:
                            type: array
                            description: Sensitivity settings for different time periods
                            items:
                              type: object
                              properties:
                                beginHour:
                                  type: integer
                                  minimum: 0
                                  maximum: 23
                                beginMin:
                                  type: integer
                                  minimum: 0
                                  maximum: 59
                                endHour:
                                  type: integer
                                  minimum: 0
                                  maximum: 23
                                endMin:
                                  type: integer
                                  minimum: 0
                                  maximum: 59
                                sensitivity:
                                  type: integer
                                  description: Sensitivity level
                          type:
                            type: string
                            description: Alarm type (e.g., "md" for motion detection)
      responses:
        '200':
          description: Alarm configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetMdAlarm:
    post:
      tags:
        - Alarm
      summary: Get motion detection alarm configuration
      description: |
        Get motion detection alarm settings including detection zones and sensitivity.

        **Important Structures:**

        **Scope Table:**
        - Defines the motion detection zone as a grid
        - Grid size: 80 columns × 60 rows (or 80×45 on some models)
        - Total characters: 4800 (80×60) or 3600 (80×45)
        - Each character represents a cell: '1' = detection enabled, '0' = detection disabled
        - The table string is a continuous string of 1s and 0s representing the entire grid

        **Sensitivity Configuration (newSens):**
        - Supports up to 4 time periods per day with different sensitivity levels
        - Each period has: id, beginHour, beginMin, endHour, endMin, enable, priority, sensitivity
        - `sensDef`: Default sensitivity value (0-100)
        - `useNewSens`: 0 = use old sensitivity, 1 = use new time-based sensitivity

        **Legacy Sensitivity (sens):**
        - Array of 4 time periods with sensitivity settings
        - Each period: id, beginHour, beginMin, endHour, endMin, sensitivity
        - Sensitivity range: 0-100 (higher = more sensitive)
      operationId: getMdAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetMdAlarm]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
            example:
              - cmd: GetMdAlarm
                action: 1
                param:
                  channel: 0
      responses:
        '200':
          description: Motion detection alarm configuration with scope table and sensitivity settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: GetMdAlarm
                    code:
                      type: integer
                      example: 0
                    value:
                      type: object
                      properties:
                        MdAlarm:
                          type: object
                          properties:
                            channel:
                              type: integer
                            scope:
                              type: object
                              properties:
                                cols:
                                  type: integer
                                  example: 80
                                  description: Number of columns in detection grid
                                rows:
                                  type: integer
                                  example: 60
                                  description: Number of rows in detection grid (60 or 45)
                                table:
                                  type: string
                                  description: Grid string of 1s and 0s (length = cols × rows)
                            newSens:
                              type: object
                              description: New time-based sensitivity configuration
                              properties:
                                sens:
                                  type: array
                                  maxItems: 4
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: integer
                                      beginHour:
                                        type: integer
                                        minimum: 0
                                        maximum: 23
                                      beginMin:
                                        type: integer
                                        minimum: 0
                                        maximum: 59
                                      endHour:
                                        type: integer
                                        minimum: 0
                                        maximum: 23
                                      endMin:
                                        type: integer
                                        minimum: 0
                                        maximum: 59
                                      enable:
                                        type: integer
                                        enum: [0, 1]
                                      priority:
                                        type: integer
                                      sensitivity:
                                        type: integer
                                        minimum: 0
                                        maximum: 100
                                sensDef:
                                  type: integer
                                  minimum: 0
                                  maximum: 100
                                  description: Default sensitivity
                            useNewSens:
                              type: integer
                              enum: [0, 1]
                              description: "0: use legacy sens, 1: use newSens"

  /api.cgi?cmd=SetMdAlarm:
    post:
      tags:
        - Alarm
      summary: Set motion detection alarm configuration
      description: |
        Set motion detection alarm settings including detection zones and sensitivity.

        **Important Notes:**
        - The scope table must match the grid size (80×60 or 80×45)
        - Each character in the table string must be '0' or '1'
        - Time periods in sensitivity configuration should not overlap
        - Use `useNewSens: 1` to enable time-based sensitivity
      operationId: setMdAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetMdAlarm]
                  param:
                    type: object
                    properties:
                      MdAlarm:
                        type: object
                        description: Motion detection alarm configuration
                        required:
                          - channel
                        properties:
                          channel:
                            type: integer
                            description: IPC channel number
                          scope:
                            type: object
                            description: Motion detection scope/area
                            properties:
                              cols:
                                type: integer
                                description: Number of columns (typically 120 or 80)
                              rows:
                                type: integer
                                description: Number of rows (typically 67 or 45)
                              table:
                                type: string
                                description: Detection grid (cols × rows characters)
                          useNewSens:
                            type: integer
                            enum: [0, 1]
                            description: Use new sensitivity structure (1=enabled)
                          newSens:
                            type: object
                            description: New sensitivity structure (when useNewSens=1)
                            properties:
                              sensDef:
                                type: integer
                                description: Default sensitivity
                              sens:
                                type: array
                                description: Time-based sensitivity settings
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: integer
                                    beginHour:
                                      type: integer
                                      minimum: 0
                                      maximum: 23
                                    beginMin:
                                      type: integer
                                      minimum: 0
                                      maximum: 59
                                    endHour:
                                      type: integer
                                      minimum: 0
                                      maximum: 23
                                    endMin:
                                      type: integer
                                      minimum: 0
                                      maximum: 59
                                    enable:
                                      type: integer
                                      enum: [0, 1]
                                    priority:
                                      type: integer
                                    sensitivity:
                                      type: integer
                                      description: Sensitivity level
            example:
              - cmd: SetMdAlarm
                param:
                  MdAlarm:
                    channel: 0
                    useNewSens: 1
                    newSens:
                      sensDef: 25
                      sens:
                        - id: 0
                          beginHour: 0
                          beginMin: 0
                          endHour: 6
                          endMin: 0
                          enable: 1
                          priority: 0
                          sensitivity: 50
                        - id: 1
                          beginHour: 6
                          beginMin: 0
                          endHour: 18
                          endMin: 0
                          enable: 1
                          priority: 0
                          sensitivity: 75
      responses:
        '200':
          description: Motion detection alarm configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                      example: SetMdAlarm
                    code:
                      type: integer
                      example: 0
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          example: 200

  /api.cgi?cmd=GetMdState:
    post:
      tags:
        - Alarm
      summary: Get motion detection state
      description: Get current motion detection alarm state
      operationId: getMdState
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetMdState]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Motion detection state
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        state:
                          type: integer
                          enum: [0, 1]
                          description: Motion detection state (0=no motion, 1=motion detected)

  /api.cgi?cmd=GetAudioAlarm:
    post:
      tags:
        - Alarm
      summary: Get audio alarm configuration
      description: |
        Get audio detection alarm settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `GetAudioAlarmV20` instead for enhanced features.
      operationId: getAudioAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAudioAlarm]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
      responses:
        '200':
          description: Audio alarm configuration

  /api.cgi?cmd=SetAudioAlarm:
    post:
      tags:
        - Alarm
      summary: Set audio alarm configuration
      description: |
        Set audio detection alarm settings.

        **Version Note:** When `scheduleVersion.ver = 1` in the capability set (from GetAbility),
        use `SetAudioAlarmV20` instead for enhanced features.
      operationId: setAudioAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Audio alarm configuration updated

  /api.cgi?cmd=GetAudioAlarmV20:
    post:
      tags:
        - Alarm
      summary: Get audio alarm configuration (v2.0)
      description: |
        Get audio detection alarm settings (version 2.0 with enhanced features).

        **Version Note:** Use this command when `scheduleVersion.ver = 1` in the capability set (from GetAbility).
      operationId: getAudioAlarmV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAudioAlarmV20]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Audio alarm configuration (v2.0)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        AudioAlarm:
                          type: object
                          properties:
                            channel:
                              type: integer
                            enable:
                              type: integer
                              enum: [0, 1]
                            sensitivity:
                              type: integer
                            schedule:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                table:
                                  type: object
                                  description: Schedule tables for different alarm types
                                  properties:
                                    MD:
                                      type: string
                                      description: Motion detection schedule (168 chars)
                                    AI_PEOPLE:
                                      type: string
                                      description: AI people detection schedule (168 chars)
                                    AI_VEHICLE:
                                      type: string
                                      description: AI vehicle detection schedule (168 chars)
                                    AI_DOG_CAT:
                                      type: string
                                      description: AI dog/cat detection schedule (168 chars)

  /api.cgi?cmd=SetAudioAlarmV20:
    post:
      tags:
        - Alarm
      summary: Set audio alarm configuration (v2.0)
      description: Set audio detection alarm settings (version 2.0)
      operationId: setAudioAlarmV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Audio alarm configuration updated

  /api.cgi?cmd=GetBuzzerAlarmV20:
    post:
      tags:
        - Alarm
      summary: Get buzzer alarm configuration (v2.0)
      description: Get buzzer alarm settings (version 2.0)
      operationId: getBuzzerAlarmV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetBuzzerAlarmV20]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Buzzer alarm configuration (v2.0)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        BuzzerAlarm:
                          type: object
                          properties:
                            channel:
                              type: integer
                            enable:
                              type: integer
                              enum: [0, 1]
                            schedule:
                              type: object
                              properties:
                                enable:
                                  type: integer
                                  enum: [0, 1]
                                table:
                                  type: object
                                  description: Schedule tables for different alarm types
                                  properties:
                                    MD:
                                      type: string
                                      description: Motion detection schedule (168 chars)
                                    AI_PEOPLE:
                                      type: string
                                      description: AI people detection schedule (168 chars)
                                    AI_VEHICLE:
                                      type: string
                                      description: AI vehicle detection schedule (168 chars)
                                    AI_DOG_CAT:
                                      type: string
                                      description: AI dog/cat detection schedule (168 chars)

  /api.cgi?cmd=SetBuzzerAlarmV20:
    post:
      tags:
        - Alarm
      summary: Set buzzer alarm configuration (v2.0)
      description: Set buzzer alarm settings (version 2.0)
      operationId: setBuzzerAlarmV20
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Buzzer alarm configuration updated

  /api.cgi?cmd=AudioAlarmPlay:
    post:
      tags:
        - Alarm
      summary: Play audio alarm
      description: Play audio alarm sound
      operationId: audioAlarmPlay
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [AudioAlarmPlay]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                      alarm_mode:
                        type: string
                      manual_switch:
                        type: integer
                        enum: [0, 1]
                      times:
                        type: integer
      responses:
        '200':
          description: Audio alarm playing

  # ==================== LED ENDPOINTS ====================

  /api.cgi?cmd=GetIrLights:
    post:
      tags:
        - LED
      summary: Get IR lights configuration
      description: |
        Get infrared LED lights settings.

        **States:** Auto, On, Off
      operationId: getIrLights
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetIrLights]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
            example:
              - cmd: GetIrLights
                action: 1
      responses:
        '200':
          description: IR lights configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        IrLights:
                          type: object
                          properties:
                            state:
                              type: string
                              enum: [Auto, On, Off]
                              description: IR lights state

  /api.cgi?cmd=SetIrLights:
    post:
      tags:
        - LED
      summary: Set IR lights configuration
      description: |
        Set infrared LED lights settings.

        **States:** Auto, On, Off
      operationId: setIrLights
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetIrLights]
                  param:
                    type: object
                    properties:
                      IrLights:
                        type: object
                        required:
                          - channel
                          - state
                        properties:
                          channel:
                            type: integer
                            description: Channel number (0-based)
                          state:
                            type: string
                            enum: [Auto, On, Off]
                            description: IR lights state
            example:
              - cmd: SetIrLights
                param:
                  IrLights:
                    channel: 0
                    state: Auto
      responses:
        '200':
          description: IR lights configuration updated

  /api.cgi?cmd=GetPowerLed:
    post:
      tags:
        - LED
      summary: Get power LED configuration
      description: Get power indicator LED settings
      operationId: getPowerLed
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetPowerLed]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: Power LED configuration

  /api.cgi?cmd=SetPowerLed:
    post:
      tags:
        - LED
      summary: Set power LED configuration
      description: Set power indicator LED settings
      operationId: setPowerLed
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetPowerLed]
                  param:
                    type: object
                    properties:
                      PowerLed:
                        type: object
                        required:
                          - channel
                          - state
                        properties:
                          channel:
                            type: integer
                            description: Channel number (0-based)
                          state:
                            type: string
                            enum: ["Auto", "Off"]
                            description: Power LED state
            example:
              - cmd: SetPowerLed
                param:
                  PowerLed:
                    channel: 0
                    state: "Auto"
      responses:
        '200':
          description: Power LED configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetWhiteLed:
    post:
      tags:
        - LED
      summary: Get white LED configuration
      description: |
        Get white spotlight/floodlight settings.

        **Modes:**
        - 0: Always light at night
        - 1: Alarm trigger mode
        - 2: Auto mode with AI detection

        **Brightness:** 0-100

        **AI Detection Types:** people, vehicle, dog_cat, face
      operationId: getWhiteLed
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetWhiteLed]
                  action:
                    type: integer
                    enum: [0, 1]
                    description: "0: get value only, 1: get initial, range, and value"
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Channel number (0-based)
            example:
              - cmd: GetWhiteLed
                action: 1
                param:
                  channel: 0
      responses:
        '200':
          description: White LED configuration with AI detection settings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        WhiteLed:
                          type: object
                          properties:
                            channel:
                              type: integer
                            state:
                              type: integer
                              enum: [0, 1]
                              description: "0: Off, 1: On"
                            mode:
                              type: integer
                              enum: [0, 1, 2]
                              description: "0: always light at night, 1: alarm trigger, 2: auto"
                            bright:
                              type: integer
                              minimum: 0
                              maximum: 100
                              description: Brightness level (0-100)
                            LightingSchedule:
                              type: object
                              properties:
                                StartHour:
                                  type: integer
                                  minimum: 0
                                  maximum: 23
                                StartMin:
                                  type: integer
                                  minimum: 0
                                  maximum: 59
                                EndHour:
                                  type: integer
                                  minimum: 0
                                  maximum: 23
                                EndMin:
                                  type: integer
                                  minimum: 0
                                  maximum: 59
                            wlAiDetectType:
                              type: object
                              description: AI detection types that trigger white LED
                              properties:
                                people:
                                  type: integer
                                  enum: [0, 1]
                                vehicle:
                                  type: integer
                                  enum: [0, 1]
                                dog_cat:
                                  type: integer
                                  enum: [0, 1]
                                face:
                                  type: integer
                                  enum: [0, 1]

  /api.cgi?cmd=SetWhiteLed:
    post:
      tags:
        - LED
      summary: Set white LED configuration
      description: |
        Set white spotlight/floodlight settings.

        **Modes:**
        - 0: Always light at night
        - 1: Alarm trigger mode
        - 2: Auto mode with AI detection
      operationId: setWhiteLed
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetWhiteLed]
                  param:
                    type: object
                    properties:
                      WhiteLed:
                        type: object
                        properties:
                          channel:
                            type: integer
                          state:
                            type: integer
                            enum: [0, 1]
                          mode:
                            type: integer
                            enum: [0, 1, 2]
                          bright:
                            type: integer
                            minimum: 0
                            maximum: 100
                          LightingSchedule:
                            type: object
                            properties:
                              StartHour:
                                type: integer
                              StartMin:
                                type: integer
                              EndHour:
                                type: integer
                              EndMin:
                                type: integer
                          wlAiDetectType:
                            type: object
                            properties:
                              people:
                                type: integer
                                enum: [0, 1]
                              vehicle:
                                type: integer
                                enum: [0, 1]
                              dog_cat:
                                type: integer
                                enum: [0, 1]
                              face:
                                type: integer
                                enum: [0, 1]
            example:
              - cmd: SetWhiteLed
                param:
                  WhiteLed:
                    channel: 0
                    state: 1
                    mode: 1
                    bright: 79
                    LightingSchedule:
                      StartHour: 18
                      StartMin: 0
                      EndHour: 6
                      EndMin: 0
                    wlAiDetectType:
                      people: 1
                      vehicle: 0
                      dog_cat: 1
                      face: 0
      responses:
        '200':
          description: White LED configuration updated

  /api.cgi?cmd=GetAiAlarm:
    post:
      tags:
        - LED
      summary: Get AI alarm configuration
      description: Get AI-based alarm settings (linked to LED control)
      operationId: getAiAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAiAlarm]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: AI alarm configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        AiAlarm:
                          type: object
                          properties:
                            channel:
                              type: integer
                            ai_type:
                              type: string
                              enum: ["people", "vehicle", "dog_cat", "face"]
                            sensitivity:
                              type: integer
                            stay_time:
                              type: integer
                            width:
                              type: integer
                            height:
                              type: integer
                            scope:
                              type: object
                            min_target_height:
                              type: number
                            max_target_height:
                              type: number
                            min_target_width:
                              type: number
                            max_target_width:
                              type: number

  /api.cgi?cmd=SetAiAlarm:
    post:
      tags:
        - LED
      summary: Set AI alarm configuration
      description: |
        Set AI-based alarm settings.

        **AI Types:** people, vehicle, dog_cat, face
      operationId: setAiAlarm
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetAiAlarm]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                        description: Index of channel
                      AiAlarm:
                        type: object
                        properties:
                          ai_type:
                            type: string
                            enum: ["people", "vehicle", "dog_cat", "face"]
                            description: AI detection type
                          sensitivity:
                            type: integer
                            description: Sensitivity of AI alarm
                          stay_time:
                            type: integer
                            description: Stay time
                          width:
                            type: integer
                            description: Detection area width
                          height:
                            type: integer
                            description: Detection area height
                          scope:
                            type: object
                            description: Detection scope/area
                            properties:
                              area:
                                type: string
                                description: Detection grid (width × height characters)
                          min_target_height:
                            type: number
                            minimum: 0.0
                            maximum: 1.0
                            description: Minimum target height (0.0-1.0)
                          max_target_height:
                            type: number
                            minimum: 0.0
                            maximum: 1.0
                            description: Maximum target height (0.0-1.0)
                          min_target_width:
                            type: number
                            minimum: 0.0
                            maximum: 1.0
                            description: Minimum target width (0.0-1.0)
                          max_target_width:
                            type: number
                            minimum: 0.0
                            maximum: 1.0
                            description: Maximum target width (0.0-1.0)
            example:
              - cmd: SetAiAlarm
                param:
                  channel: 0
                  AiAlarm:
                    ai_type: people
                    sensitivity: 10
                    stay_time: 0
                    width: 80
                    height: 60
                    min_target_height: 0.0
                    max_target_height: 1.0
                    min_target_width: 0.0
                    max_target_width: 1.0
      responses:
        '200':
          description: AI alarm configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=SetAlarmArea:
    post:
      tags:
        - LED
      summary: Set alarm area
      description: Set alarm detection area/zone
      operationId: setAlarmArea
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '200':
          description: Alarm area updated

  # ==================== AI ENDPOINTS ====================

  /api.cgi?cmd=GetAiCfg:
    post:
      tags:
        - AI
      summary: Get AI configuration
      description: Get AI detection and tracking configuration (people, vehicle, pet detection)
      operationId: getAiCfg
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAiCfg]
                  action:
                    type: integer
                    enum: [0, 1]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
      responses:
        '200':
          description: AI configuration
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        channel:
                          type: integer
                        aiTrack:
                          type: integer
                          enum: [0, 1]
                          description: AI tracking switch
                        trackType:
                          type: object
                          description: AI track type configuration
                        AiDetectType:
                          type: object
                          properties:
                            people:
                              type: integer
                              enum: [0, 1]
                            vehicle:
                              type: integer
                              enum: [0, 1]
                            dog_cat:
                              type: integer
                              enum: [0, 1]
                            face:
                              type: integer
                              enum: [0, 1]

  /api.cgi?cmd=SetAiCfg:
    post:
      tags:
        - AI
      summary: Set AI configuration
      description: Set AI detection and tracking configuration
      operationId: setAiCfg
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [SetAiCfg]
                  action:
                    type: integer
                    enum: [0]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
                      aiTrack:
                        type: integer
                        enum: [0, 1]
                        description: AI tracking switch
                      trackType:
                        type: object
                        description: AI track type configuration
                      AiDetectType:
                        type: object
                        properties:
                          people:
                            type: integer
                            enum: [0, 1]
                            description: People detection
                          vehicle:
                            type: integer
                            enum: [0, 1]
                            description: Vehicle detection
                          dog_cat:
                            type: integer
                            enum: [0, 1]
                            description: Dog and cat detection
                          face:
                            type: integer
                            enum: [0, 1]
                            description: Face detection
            example:
              - cmd: SetAiCfg
                action: 0
                param:
                  aiTrack: 0
                  trackType: {}
                  AiDetectType:
                    people: 1
                    vehicle: 1
                    dog_cat: 1
                    face: 0
                  channel: 0
      responses:
        '200':
          description: AI configuration updated
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        rspCode:
                          type: integer
                          description: Response code

  /api.cgi?cmd=GetAiState:
    post:
      tags:
        - AI
      summary: Get AI alarm state
      description: Get current AI detection alarm state
      operationId: getAiState
      security:
        - tokenAuth: []
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  cmd:
                    type: string
                    enum: [GetAiState]
                  param:
                    type: object
                    properties:
                      channel:
                        type: integer
            example:
              - cmd: GetAiState
                param:
                  channel: 0
      responses:
        '200':
          description: AI alarm state
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    cmd:
                      type: string
                    code:
                      type: integer
                    value:
                      type: object
                      properties:
                        channel:
                          type: integer
                        dog_cat:
                          type: object
                          properties:
                            alarm_state:
                              type: integer
                            support:
                              type: integer
                        face:
                          type: object
                          properties:
                            alarm_state:
                              type: integer
                            support:
                              type: integer
                        people:
                          type: object
                          properties:
                            alarm_state:
                              type: integer
                            support:
                              type: integer
                        vehicle:
                          type: object
                          properties:
                            alarm_state:
                              type: integer
                            support:
                              type: integer