Nine Fives Firmware API

openapi: 3.1.0
info:
  title: Nine Fives Programmable REST Attenuator Firmware API
  version: '1.0'
  description: JSON REST API served on port 80 by the Nine Fives POE-ATTEN-6G programmable RF attenuator for programmatic control and monitoring. Faithfully transcribed from the published device reference manual; the device also exposes SCPI over raw TCP (port 5025) and HiSLIP (port 4880). No authentication is required — the API is served directly by the device over the local network (Ethernet or USB-C).
  contact:
    name: Nine Fives
    url: https://ninefives.com
  x-generated: '2026-07-20'
  x-method: generated
  x-source: https://docs.ninefives.com/attenuator/rest-api/overview/
servers:
- url: http://{deviceIp}
  description: Device-hosted API on port 80 (default Ethernet fallback IP 192.168.0.95, USB-C 192.168.42.95)
  variables:
    deviceIp:
      default: 192.168.0.95
      description: The IP address of the attenuator device on the local network
tags:
- name: Firmware
  description: Firmware status and dual-slot (A/B) updates
paths:
  /api/firmware/status:
    get:
      operationId: getFirmwareStatus
      tags:
      - Firmware
      summary: Get firmware status
      description: Returns current firmware version, dual-slot (A/B) information, and update progress.
      responses:
        '200':
          description: Firmware status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FirmwareStatus'
  /api/firmware/update:
    post:
      operationId: updateFirmware
      tags:
      - Firmware
      summary: Upload and install a firmware bundle
      description: Upload a .raucb firmware bundle (max 256 MiB) for installation. Uses multipart/form-data. The mode query parameter is empty (default) for single slot or "full" for both slots. Installation runs asynchronously; poll GET /api/firmware/status for progress.
      parameters:
      - name: mode
        in: query
        required: false
        schema:
          type: string
          enum:
          - ''
          - full
        description: Empty (default) for single slot, "full" for both slots
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                firmware:
                  type: string
                  format: binary
                  description: The .raucb file (max 256 MiB)
      responses:
        '202':
          description: Accepted — installation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusMessage'
  /api/firmware/update/url:
    post:
      operationId: updateFirmwareFromUrl
      tags:
      - Firmware
      summary: Install firmware from a URL
      responses:
        '202':
          description: Accepted — installation started
  /api/firmware/update/resume:
    post:
      operationId: resumeFirmwareUpdate
      tags:
      - Firmware
      summary: Resume a firmware update
      responses:
        '200':
          description: Update resumed
  /api/firmware/update/cancel:
    post:
      operationId: cancelFirmwareUpdate
      tags:
      - Firmware
      summary: Cancel a firmware update
      responses:
        '200':
          description: Update cancelled
components:
  schemas:
    FirmwareStatus:
      type: object
      properties:
        version:
          type: string
          description: Currently running firmware version
        activeSlot:
          type: string
          enum:
          - A
          - B
          description: Active firmware slot
        inactiveSlot:
          type: string
          enum:
          - A
          - B
        inactiveVersion:
          type: string
        updateInProgress:
          type: boolean
        updateProgress:
          type: number
          description: Progress percentage 0-100
          present during updates: null
        updateMessage:
          type: string
        updateMode:
          type: string
          description: Empty for single-slot, "full" for both-slots updates
        updatePhase:
          type: string
          enum:
          - installing_first
          - rebooting
          - installing_second
          description: Current phase during a full update
        lastError:
          type: string
    StatusMessage:
      type: object
      properties:
        status:
          type: string
        message:
          type: string