Hyperion
    Hyperion
    • JSON-RPC API Introduction
    • JSON-API Commands Overview
    • Connect to Hyperion
    • Components & Priorities
    • Hyperion API
      • Authorization
        • API Authentication - Introduction
        • createToken
        • renameToken
        • deleteToken
        • getTokenlist
        • tokenRequired
        • adminRequired
        • newPasswordRequired
        • requestToken
        • newPassword
        • answerRequest
        • getPendingTokenRequests
        • login
        • logout
      • Information
        • getSystemInformation
        • getSubscriptionInformation
        • getServerInformation
        • getImageSnapshot
        • getLedsSnapshot
      • Controls
        • Input Controls
          • setColor
          • setEffect
          • setImage
          • clear
          • clearAll
          • selectSource
        • Output Controls
          • adjustColors
          • setLedMapping
          • setVideomode
        • Subscription Controls
          • liveImageStream
          • liveLedColorStream
        • Operational Controls
          • setComponentState
          • setInstanceState
          • switchInstance
          • setSystemState
          • setSubscriptions
      • Configuration
        • createInstance
        • deleteInstance
        • renameInstance
        • getConfiguration
        • updateConfiguration
        • restoreConfiguration
        • getSchemas

    JSON-RPC API Introduction

    The JSON-RPC interfaces provides many ways to interact with Hyperion. You can retrieve
    information about your server, your instances and take actions (such as setting a color as input or switching lights off).
    The JSON-API Commands Overview provides guidance which commands can be applied in general, to single or multiple instances via one request.
    In addition, the overview outlines if authorization is required before or while sending requests (HTTP/S).
    You also find, if a command can be used via WebSocket/TCPSocket and/or HTTP/s.
    Every endpoint also has a tagging which way of communication is supported (see Connect to Hyperion).
    In case you are interested subscribing to updates, you can request selected events via setSubscriptions.
    The JSON-API Commands Overview provides guidance which subscriptions are possible to select from.

    What is JSON?#

    JSON is a standardized message format (see JSON.org) and is supported by most programming languages. It is human readable which makes for easier debugging.

    Sending JSON Requests#

    Hyperion requires JSON requests along the following scheme:
    request
    command
    string 
    required
    Command to be executed
    subcommand
    enum<string> 
    optional
    Sub-Command to be executed
    Allowed value:
    createToken
    instance
    optional
    One ore many instance idices the request is to be applied to
    One of
    Instance index (0-254) to which the command applies.
    >= 0<= 254
    tan
    integer 
    optional
    Transaction number for tracking requests and responses.
    >= 0
    Example:
    4711

    Response#

    Most requests will result in responses following the schema below:
    response
    command
    string 
    required
    The command executed
    subcommand
    string 
    optional
    The sub-command executed
    success
    boolean 
    required
    Result, if the request excuted successfully
    info
    object 
    optional
    Information requested
    Additional properties
    integer  | number  | string  | boolean 
    optional
    error
    string 
    optional
    Reason why a request did not execute successfully
    errorData
    array [object {1}] 
    optional
    Detailed error explaination
    description
    string 
    optional
    tan
    integer 
    required
    Request's transaction number

    API wrappers#

    Hyperion-py is a 3rd-party Python library for communication with Hyperion-NG. It uses the API described here as the underlying communication mechanism and presents it in a user-friendly way. As a 3rd party library, it is not supported by the Hyperion development team.
    Modified at 2025-05-19 20:28:05
    Next
    JSON-API Commands Overview
    Built with