SurgeX SX-VS-1 Series Control Spec

Summary

The SurgeX SX-VS-1 Series (Vertical Series +) is a networked power distribution unit with individually switchable AC outlets. It exposes a RESTful JSON API over HTTP or HTTPS for outlet power control, sequencing, event triggers, power monitoring, and device configuration. Authentication is required for API features. Basic Authentication and session tokens via the x-auth-token header are supported.

Transport

protocols:
  - http
  - https
addressing:
  base_url: /api/v1
  port: 80
auth:
  type: UNRESOLVED
  notes: Authentication is required for access to all API features. Basic Authentication and web session tokens using the x-auth-token header are supported.

Traits

traits:
  - powerable  # inferred from PowerOn/PowerOff/Reboot outlet commands
  - queryable  # inferred from currentStatus, WhoAreYou query endpoints

Actions

actions:
  - id: power_on_outlet
    label: Power On Outlet
    kind: action
    method: POST
    path: /api/v1/{id}/{outlet}/PowerOn
    params:
      - name: id
        type: string
        description: Device ID (always "1" for Vertical Series +)
      - name: outlet
        type: string
        description: Outlet ID or group ID (e.g. "/1/1", "/1/25")
    response:
      type: boolean
      description: "true" for success, "false" for failure
    notes: User must have DeviceControl privilege

  - id: power_off_outlet
    label: Power Off Outlet
    kind: action
    method: POST
    path: /api/v1/{id}/{outlet}/PowerOff
    params:
      - name: id
        type: string
        description: Device ID (always "1" for Vertical Series +)
      - name: outlet
        type: string
        description: Outlet ID or group ID
    response:
      type: boolean
    notes: User must have DeviceControl privilege

  - id: reboot_outlet
    label: Reboot Outlet
    kind: action
    method: POST
    path: /api/v1/{id}/{outlet}/Reboot
    params:
      - name: id
        type: string
        description: Device ID (always "1" for Vertical Series +)
      - name: outlet
        type: string
        description: Outlet ID or group ID
    response:
      type: boolean
    notes: User must have DeviceControl privilege. Reboot time is configurable per outlet (rebootTime field).

  - id: run_sequence
    label: Run Sequence
    kind: action
    method: POST
    path: /api/v1/RunSequence
    params:
      - name: id
        type: integer
        description: Sequence ID to execute
    response:
      type: boolean

  - id: enter_shutdown_state
    label: Enter Shutdown State
    kind: action
    method: POST
    path: /api/v1/EnterShutdownState
    params: []
    response:
      type: boolean
    notes: Prevents any outlet from turning on until cleared. Requires Admin privileges.

  - id: clear_shutdown_state
    label: Clear Shutdown State
    kind: action
    method: POST
    path: /api/v1/ClearShutdownState
    params: []
    response:
      type: boolean
    notes: Returns device to running state. Requires Admin privileges.

  - id: reset_energy_usage
    label: Reset Energy Usage
    kind: action
    method: POST
    path: /api/v1/ResetEnergyUsage
    params: []
    response:
      type: boolean

  - id: add_sequence
    label: Add Sequence
    kind: action
    method: POST
    path: /api/v1/AddSequence
    params:
      - name: id
        type: integer
        nullable: true
        description: Null for a new sequence
      - name: name
        type: string
        description: User-friendly sequence name
      - name: steps
        type: array
        description: Array of step objects with "method" and "delay" keys
    response:
      type: integer
      description: ID of the newly created sequence

  - id: change_sequence
    label: Change Sequence
    kind: action
    method: POST
    path: /api/v1/ChangeSequence
    params:
      - name: id
        type: integer
        description: Sequence ID to modify
      - name: name
        type: string
      - name: steps
        type: array
    response:
      type: boolean

  - id: remove_sequence
    label: Remove Sequence
    kind: action
    method: POST
    path: /api/v1/RemoveSequence
    params:
      - name: id
        type: integer
        description: Sequence ID to delete
    response:
      type: boolean

  - id: add_trigger
    label: Add Trigger
    kind: action
    method: POST
    path: /api/v1/AddTrigger
    params:
      - name: id
        type: integer
        description: "0 for new trigger"
      - name: enabled
        type: boolean
      - name: name
        type: string
      - name: type
        type: string
        description: "ThresholdSamples, Schedule, Autoping, or GpioStateChange"
      - name: expressions
        type: object
        description: On/off evaluation criteria
      - name: actions
        type: array
        description: Actions to take on state transitions
    response:
      type: object
      description: The newly created trigger object

  - id: change_trigger
    label: Change Trigger
    kind: action
    method: POST
    path: /api/v1/ChangeTrigger
    params:
      - name: id
        type: string
        required: true
        description: UUID of the trigger to modify
      - name: enabled
        type: boolean
        required: true
      - name: name
        type: string
        required: true
      - name: type
        type: string
        required: true
        description: "ThresholdSamples, Schedule, Autoping, or GpioStateChange"
      - name: actions
        type: array
        required: true
        description: Action objects for on and off state transitions
      - name: expressions
        type: object
        required: true
        description: On/off evaluation criteria
    response:
      type: string
      description: UUID of the changed trigger
    notes: Request body is an array containing the trigger object.

  - id: change_network_settings
    label: Change Network Settings
    kind: action
    method: PUT
    path: /api/v1/networkSettings
    params:
      - name: httpd
        type: object
        description: Web server settings (enabled, ssl, port)
      - name: ethInterfaces
        type: array
        description: Ethernet interface configurations

  - id: change_device_settings
    label: Change Device Settings
    kind: action
    method: PUT
    path: /api/v1/deviceSettings
    params:
      - name: verticalseries
        type: object
        description: Device object including name, outlets, groups, and device measurements
      - name: sequences
        type: array
        description: Sequence objects
      - name: startupProcedure
        type: object
        description: Startup procedure configuration

  - id: change_user
    label: Change User
    kind: action
    method: POST
    path: /api/v1/UserChange
    params:
      - name: username
        type: string
        required: true
      - name: authmode
        type: string
      - name: email
        type: string
      - name: admin
        type: string
        description: "admin" or "user"
      - name: passwd
        type: string
      - name: name
        type: string
      - name: privs
        type: array
        description: "Array of: TriggerConfig, DeviceControl, NetworkSettings, SoftwareUpdate, UserAdmin"

  - id: add_user
    label: Add User
    kind: action
    method: POST
    path: /api/v1/UserAdd
    params:
      - name: username
        type: string
        required: true
      - name: authmode
        type: string
        required: true
        description: "internal" or "ldap"
      - name: name
        type: string
        required: true
      - name: admin
        type: string
        required: true
      - name: privs
        type: array
        required: true
      - name: passwd
        type: string
        required: false
        description: Required when authmode is "internal"; ignored when authmode is "ldap"
    response:
      type: array
      description: "[index, username]"

  - id: delete_user
    label: Delete User
    kind: action
    method: POST
    path: /api/v1/UserDel
    params:
      - name: username
        type: string
        required: true
    response:
      type: array
      description: "[index, username]"

  - id: upload_file
    label: Upload File
    kind: action
    method: POST
    path: /api/v1/UploadFile
    params:
      - name: file
        type: file
        description: "multipart/form-data. name options: fwupdate.img, verticalseriesPlus.cfg, snmpd.conf, ssl.crt, ssl.key, cert.ca, wpa_supplicant.conf, wpa_cert.ca, wpa_user.crt, wpa_user.prv, wpa_fast.pac"

Feedbacks

feedbacks:
  - id: current_status
    label: Current Status
    method: GET
    path: /api/v1/currentStatus
    query_command: GET /api/v1/currentStatus
    type: object
    description: Full device status including model, serial, activeState, firmware, devices with measurements, groups, and outlets
    fields:
      - name: activeState
        type: enum
        values: [Startup, Running, Shutdown]
      - name: firmware
        type: string
      - name: model
        type: string
      - name: serial
        type: string

  - id: outlet_state
    label: Outlet State
    type: enum
    values: ["0", "1", "2"]
    description: "0 = off, 1 = on, 2 = rebooting. Found in currentStatus.outlets[].state"

  - id: who_are_you
    label: Device Identity
    method: GET
    path: /api/v1/WhoAreYou
    query_command: GET /api/v1/WhoAreYou
    type: object
    description: Device identity including model, serial, MAC, hostname, firmware, manufacturer, deviceType

  - id: network_settings
    label: Network Settings
    method: GET
    path: /api/v1/networkSettings
    query_command: GET /api/v1/networkSettings
    type: object
    description: Network interface config, HTTP server settings, SNMP config, NTP, mDNS

  - id: device_settings
    label: Device Settings
    method: GET
    path: /api/v1/deviceSettings
    query_command: GET /api/v1/deviceSettings
    type: object
    description: Device configuration including sequences, startup procedure, outlet/group settings

  - id: sequences
    label: Sequences
    method: GET
    path: /api/v1/sequences
    query_command: GET /api/v1/sequences
    type: array
    description: List of all configured sequences with steps, running state, and current step

  - id: event_settings
    label: Event Settings
    method: GET
    path: /api/v1/EventSettings
    query_command: GET /api/v1/EventSettings
    type: object
    description: Trigger configurations including threshold, schedule, autoping, and GPIO state change triggers

  - id: users
    label: Users
    method: GET
    path: /api/v1/users
    query_command: GET /api/v1/users
    type: array
    description: List of configured users with privileges

  - id: time_stamped_events
    label: Time Stamped Events
    method: POST
    path: /api/v1/TimeStampedEvents
    query_command: POST /api/v1/TimeStampedEvents
    type: object
    params:
      - name: startDate
        type: string
        required: true
      - name: endDate
        type: string
        required: true
    description: Events logged between specified dates. Returns trigger events, system events, control events.

  - id: historical_data_info
    label: Historical Data Info
    method: POST
    path: /api/v1/LogFileInfo
    query_command: POST /api/v1/LogFileInfo
    type: object
    params:
      - name: logType
        type: string
        description: "e.g. \"VerticalSeriesData\""
    description: Schema and file list for historical power measurement data logs

  - id: device_measurements
    label: Device Measurements
    type: object
    description: Power measurements found in currentStatus.devices[].deviceMeasurements
    fields:
      - name: voltageLN
        type: number
        description: Line to neutral voltage (V)
      - name: current
        type: number
        description: Total AC current (A)
      - name: power
        type: number
        description: Average power (W)
      - name: frequency
        type: number
        description: Frequency (Hz)
      - name: temperature
        type: number
        description: Internal temperature (units per temperatureUnits setting)
      - name: pf
        type: number
        description: Power factor (0 to 1)
      - name: energyUsage
        type: number
        description: Energy usage since last reset (Wh)
      - name: crestFactor
        type: number
        description: Line to neutral voltage crest factor
      - name: crestFactorNG
        type: number
        description: Neutral to ground voltage crest factor

  - id: input_state
    label: Input State
    type: enum
    values: [No Ground, Reverse Polarity, Wiring Fault]
    description: Reports input power abnormalities

Variables

variables:
  - id: outlet_name
    label: Outlet Name
    path: currentStatus.outlets[].name
    type: string
    description: User-configurable outlet name

  - id: outlet_initial_state
    label: Outlet Initial State
    path: deviceSettings.outlets[].initialState
    type: enum
    values: ["0", "1", "2", "3", "4", "5"]
    description: "Startup behavior: 0=always on, 1=always off, 2=shutdown, 3=on, 4=off, 5=last state"

  - id: outlet_reboot_time
    label: Outlet Reboot Time
    path: currentStatus.outlets[].rebootTime
    type: integer
    description: Delay in seconds between off and on during reboot

  - id: temperature_units
    label: Temperature Units
    type: enum
    values: [F, C]

  - id: auto_logout_time
    label: Auto Logout Time
    type: integer
    description: Minutes before web session auto-logout

  - id: http_port
    label: HTTP Server Port
    type: integer
    description: Configurable web server port (default 80)

Events

events:
  - id: trigger_on
    description: Trigger entered active/on state (alertLevel 2)
    fields:
      - name: type
        values: [Trigger (On)]
      - name: message.action.type
        values: [PowerOn, PowerOff, Reboot]

  - id: trigger_off
    description: Trigger returned to off/clear state
    fields:
      - name: type
        values: [Trigger (Off)]

  - id: system_event
    description: System events (login, logout, NTP sync)
    fields:
      - name: type
        values: [System]

  - id: device_control_event
    description: Outlet control confirmation events
    fields:
      - name: type
        values: [DeviceControl]

Macros

macros:
  - id: startup_sequence
    label: Startup Sequence
    description: >
      A configured sequence of outlet power-on commands with delays between steps.
      Executed automatically on power-up when startupProcedure is set to RunSequence.
      Steps use syntax /{ID}/{OUTLET}/{COMMAND} where COMMAND is PowerOn, PowerOff, or Reboot.
    params:
      - name: steps
        type: array
        description: Array of {method: string, delay: integer_seconds}

Safety

confirmation_required_for:
  - enter_shutdown_state
  - clear_shutdown_state
interlocks:
  - shutdown_state: When device is in shutdown state, no outlets can be turned on via manual control until shutdown is cleared
  - admin_required: EnterShutdownState and ClearShutdownState require Admin privileges
  - privilege_check: Outlet control commands require DeviceControl privilege; user admin requires UserAdmin privilege
# UNRESOLVED: specific power-on sequencing safety requirements not stated in source
# UNRESOLVED: maximum inrush current or simultaneous outlet power-on limits not stated

Notes

• Protocol version is embedded in the URI (currently v1). Firmware updates may introduce new protocol versions; multiple versions may coexist.
• Outlet IDs follow the pattern /{device_id}/{outlet_number} where device_id is always "1" for Vertical Series +.
• Groups (e.g. "All Outlets" with id "/1/25") can be used as targets for power commands.
• mDNS discovery is supported on port 5353 for dynamic device discovery on the network.
• Sequence steps support the commands: PowerOn, PowerOff, Reboot. Step delay is in seconds.
• Trigger types: ThresholdSamples (power measurement thresholds), Schedule (date/time), Autoping (IP ping monitoring), GpioStateChange (GPIO feedback).
• Historical data logs are stored as gzipped CSV files accessible via HTTP GET.
• Default HTTP port is 80, but is configurable. Examples in the source use port 8080.

Provenance

source_domains:
  - ametekesp.com
source_urls:
  - https://www.ametekesp.com/-/media/ametekesp/downloads/manuals/vertical-series-plus/api-definition-vertical-series.pdf
retrieved_at: 2026-04-30T04:31:27.393Z
last_checked_at: 2026-10-07T16:11:38.721Z

Verification Summary

verdict: verified
checked_at: 2026-10-07T16:11:38.721Z
matched_actions: 27
action_count: 27
confidence: medium
summary: "All 27 action units (18 actions, 9 query feedbacks) match documented endpoints; port 80 and /api/v1 are supported; no unrepresented source commands. (7 unresolved item(s) noted in Known Gaps.)"

Known Gaps

- "exact model variants in the SX-VS-1 Series family beyond SX-VS-1216 are not enumerated in source"
- "HTTPS/TLS configuration details beyond ssl boolean flag not documented"
- "specific power-on sequencing safety requirements not stated in source"
- "maximum inrush current or simultaneous outlet power-on limits not stated"
- "maximum number of outlets per model variant not explicitly stated (SX-VS-1216 has 16)"
- "SNMP trap payload format not documented"
- "firmware update procedure details beyond file upload not documented"

From the AI4AV catalog (https://ai4av.net) · ODbL-1.0