Skip to content

JSON RPC 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 priority input).

What is JSON?

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

Sending JSON

Hyperion requires a specially formatted JSON message. A command argument is always required. A tan argument is optional. This is an integer you can freely choose -- it is part of the response you will receive to allow you to filter the response from other server messages (this functionality is likely necessary for advanced usecases only).

  "command" : "YourCommand",
  "tan" : 1

Depending on the command, there might be an additional subcommand required:

  "command" : "YourCommand",
  "subcommand" : "YourSubCommand",
  "tan" : 1


Most messages you send will trigger a response of the following format:

  "command" : "YourCommand",
  "info":{ ...DATA... },
  "instance": 0,  
  "success" : true,
  "tan" : 1
  • command: The command you requested.
  • tan: The tan you provided (If not, it will default to 0 in the response).
  • instance: Instance# sent the update
  • success: true or false. If false, an error argument will contain details of the issue.
  • info: The data you requested (if any).


Hyperion currently supports multiple connection mechanisms: TCP Socket ("Json Server"), WebSocket and HTTP/S.


You can automatically discover Hyperion servers! See Detect Hyperion

TCP Socket

This is a "raw" connection, you can send and receive line-separated json from the server (default port: 19444). This is also known as the "Json Server".


This is part of the Hyperion webserver (default port: 8090). You send and receive json commands. WSS is also supported on port 8092. Only TEXT mode is supported. Read more about websockets at Websocket.


HTTP requests can also be sent to the webserver (default port: 8090, for HTTPS: 8092). Send a HTTP/S POST request along with a properly formatted json message in the body to the (example) url: http://IpOfDevice:WebserverPort/json-rpc

Control Hyperion with HTTP JSON RPC

Example picture with a Firefox/Chrome Addon to send HTTP JSON messages


If you get a "No Authorization" response, you need to create an Authorization Token

HTTP/S Restrictions

Please note that the HTTP JSON-RPC lacks of the following functions due to technical limitations.

  • Image streams, led color streams, logging streams, subscriptions


Server Info

A large variety of data is available from the server: Server Info


Control your Hyperion server: Control


Authentication mechanisms: Authentication


Data subscriptions: Subscribe

3rd Party Libraries

  • 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.