Controlling Proxima via REST API

The Proxima 4020, 4040, and 4060 servers can be controlled remotely via a simple and effective REST API interface. This public API allows you to control the audio volume, manage the mute status, and perform system actions such as restarting or shutting down.

This document presents all available endpoints, how they work, and a concrete example of HTML/JavaScript integration.

TABLE DES MATIÈRES

• Available REST API public access documentation
  • Player API
    • Mute
    • Unmute
    • Toggle mute
    • Set and get the volume
    • Set Maintenance Mode
  • Power API
    • Reboot
    • Shutdown
• HTML/JavaScript example

Available REST API public access documentation

In this section, you'll find the list of all available API endpoints grouped by functionality. Each endpoint is briefly described to help you identify which one suits your integration needs.

Player API

Mute

• Method: POST or GET
• API path:

  /api/player/mute
  

• Description: Enable the audio mute.
• Authentication: (none)
• Query parameters: (no parameters)
• Examples:

  http://192.168.1.1/api/player/mute                    // enable the audio mute
  

• Responses:

  Code	Type	Description	Returns
  200	Success	The request has succeeded	(null)
  417	Error	Expectation failed	(null)

Unmute

• Method: POST or GET 
• API path:

  /api/player/unmute
  

• Description: Disable the audio mute.
• Authentication: (none)
• Query parameters: (no parameters)
• Examples:

  http://192.168.1.1/api/player/unmute                    // disable the audio mute
  

• Responses:

  Code	Type	Description	Returns
  200	Success	The request has succeeded	(null)
  417	Error	Expectation failed	(null)

Toggle mute

• Method: POST or GET 
• API path:

  /api/player/toggle-mute
  

• Description: Toggle the audio mute.
• Authentication: (none)
• Query parameters: (no parameters)
• Examples:

  http://192.168.1.1/api/player/toggle-mute                    // toggle the audio mute
  

• Responses:

  Code	Type	Description	Returns
  200	Success	The request has succeeded	(null)
  417	Error	Expectation failed	(null)

Set and get the volume

• Method: POST or GET 

• API path:

  /api/player/set-volume?volume=<number>&relative=<boolean>
  

• Description: Set and get the audio volume (absolute or relative).

• Authentication: (none)

• Query parameters:

  Field	Type	Description
  volume (required)	Number	The volume level [0...100]
  relative (optional)	Boolean	Whether the volume level is relative to the current volume. Default value: false

  
  

• Examples:

  http://192.168.1.1/api/player/set-volume                              // Get the volume
  http://192.168.1.1/api/player/set-volume?volume=60                    // set the volume to 60
  http://192.168.1.1/api/player/set-volume?volume=10&relative=true      // Increase the volume by 10
  http://192.168.1.1/api/player/set-volume?volume=-20&relative=true     // Decrease the volume by 20
  http://192.168.1.1/api/player/set-volume?volume=85&relative=false     // Set the volume to 85
  

• Responses:

  Code	Type	Description	Returns
  200	Success	The request has succeeded	JSON
  417	Error	Expectation failed	(null)

  200 success response body (JSON):

  {
    "volume": number,    // current volume value
    "mute:": boolean     // current mute state
  }
  

  200 success response example:

  {
    "volume": 50,    // the volume is set to 50
    "mute:": false   // the mute is set to false
  }
  

Set Maintenance Mode

• Method: POST or GET
• API path:

  /api/player/maintenance
  

• Description: true to set maintenance mode, false to quit maintenance mode (=restart Composer)
• Authentication: (none)
• Query parameters:

  Field	Type	Description
  value (required)	Bool	true -> set maintenance mode, false -> quit maintenance mode

• Examples:

  http://192.168.1.1/api/player/maintenance?value=true   // set the server in maintenance mode = stop Composer
  http://192.168.1.1/api/player/maintenance?value=false  // quit maintenance mode = restart Composer
  

• Responses:

  Code	Type	Description	Returns
  200	Success	The request has succeeded	(null)
  400	Error	Bad Request (value is not properly written)	(null)
  417	Error	Expectation failed	(null)

Power API

Reboot

• Method: POST or GET 
• API path:

  /api/power/reboot
  

• Description: Reboot the server.
• Authentication: (none)
• Query parameters: (no parameters)
• Examples:

  http://192.168.1.1/api/power/reboot                    // reboot the server
  

• Responses:

  Code	Type	Description	Returns
  200	Success	The request has succeeded	(null)
  417	Error	Expectation failed	(null)

Shutdown

• Method: POST or GET 
• API path:

  /api/player/shutdown
  

• Description: shutdown the server
• Authentication: (none)
• Query parameters: (no parameters)
• Examples:

  http://192.168.1.1/api/power/shutdown                    // shutdown the server
  

• Responses:

  Code	Type	Description	Returns
  200	Success	The request has succeeded	(null)
  417	Error	Expectation failed	(null)

HTML/JavaScript example

Below is a ready-to-use HTML/JavaScript interface to test and integrate the Proxima REST API. You can directly edit the IP address and parameters to match your configuration. 

(Edit the ProximaURL variable to match with the IPv4 address of your Proxima server):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Call REST API Proxima</title>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 20px;
    }
    #response {
      margin-top: 20px;
      padding: 10px;
      border: 1px solid #ccc;
      background-color: #f9f9f9;
      white-space: pre-wrap;
    }
    button {
      padding: 10px 15px;
      background-color: #007bff;
      color: white;
      border: none;
      border-radius: 5px;
      cursor: pointer;
      margin: 2px 2px 2px 2px;
    }
    button:hover {
      background-color: #0056b3;
    }
  </style>
</head>
<body>
  <h1>Call REST API with JavaScript</h1>    
  <div>
    <button id="apiButtonGetVolume">API Get Volume</button>    
  </div>
  <div>
    <button id="apiButtonVolumeRelative">API Set Volume Relatif</button>    
    <input type="number" id="apiVolumeRelativeParameter1" min="-100" max="100" value="0" />
  </div>
  <div>
    <button id="apiButtonVolumeAbsolute">API Set Volume Absolu</button>
    <input type="number" id="apiVolumeAbsoluteParameter1" min="0" max="100" value="70"/>    
  </div>
  <div>
    <button id="apiButtonMute">API Mute</button>
    <button id="apiButtonUnmute">API Unmute</button>
    <button id="apiButtonToggleMute">API ToggleMute</button>
  </div>
  <div>
    <button id="apiButtonMaintenanceOn">API Maintenance On</button>
    <button id="apiButtonMaintenanceOff">API Maintenance Off</button>    
  </div>
  <div>
    <button id="apiButtonReboot">API Reboot</button>
    <button id="apiButtonShutdown">API Shutdown</button>
  </div>
  <div id="response">The answer of the API is displayed here.</div>
  <script>
    // Function to call REST API
    const ProximaURL = 'http://192.168.1.1'; // URL of the Proxima server
    const apiUrlVolume = ProximaURL + '/api/player/set-volume'; // Set relative or absolute volume and Get volume and mute settings
    const apiUrlMute = ProximaURL + '/api/player/mute'; // Set mute 
    const apiUrlUnmute = ProximaURL + '/api/player/unmute'; // Set unmute 
    const apiUrlToggleMute = ProximaURL + '/api/player/toggle-mute'; // Toggle mute/unmute    
    const apiUrlMaintenanceOn = ProximaURL + '/api/player/maintenance?value=true'; // Maintenance On
    const apiUrlMaintenanceOff = ProximaURL + '/api/player/maintenance?value=false'; // Maintenance Off    
    const apiUrlReboot = ProximaURL + '/api/system/reboot'; // Reboot
    const apiUrlShutdown = ProximaURL + '/api/system/shutdown'; // Shutdown
    async function callApi(arg1, arg2, arg3) {
      try {
        document.getElementById('response').textContent = '';
        let APIUrl;
        if (arg2 !== undefined && arg3 !== undefined) {
          const completeArg1 = '?volume=';
          const completeArg2 = '&relative=';
          APIUrl = `${arg1 + completeArg1 + arg2 + completeArg2 + arg3}`;
        }
        else {
          APIUrl = arg1;
        }
        // Do the GET request
        const response = await fetch(APIUrl, { method: "POST" });                               
        if (arg1 !== apiUrlVolume) {
          document.getElementById('response').textContent = 'Request sent!';                    
        }
        else {
          if (!response.ok) {
            throw new Error(`Erreur HTTP ! statut : ${response.status}`);
          }
          // Convert the JSON answer
          const data = await response.json();
          // Display the answer in a div
          document.getElementById('response').textContent = JSON.stringify(data, null, 2);
        }
      } catch (error) {
        // Display the error in a div
        document.getElementById('response').textContent = `Erreur : ${error.message}`;
        }
    }
    async function callApiPlus(arg1, arg2) {
    callApi(arg1);
    callApi(apiUrlVolume);
    }
    // Add event manager for each button
    document.getElementById('apiButtonGetVolume').addEventListener('click', () => callApi(apiUrlVolume));
    document.getElementById('apiButtonVolumeRelative').addEventListener('click', () => callApi(apiUrlVolume, document.getElementById('apiVolumeRelativeParameter1').value, true));        
    document.getElementById('apiButtonVolumeAbsolute').addEventListener('click', () => callApi(apiUrlVolume, document.getElementById('apiVolumeAbsoluteParameter1').value, false));
    document.getElementById('apiButtonMute').addEventListener('click', () => callApiPlus(apiUrlMute, apiUrlVolume));
    document.getElementById('apiButtonUnmute').addEventListener('click', () => callApiPlus(apiUrlUnmute, apiUrlVolume));
    document.getElementById('apiButtonToggleMute').addEventListener('click', () => callApiPlus(apiUrlToggleMute, apiUrlVolume));    
    document.getElementById('apiButtonMaintenanceOn').addEventListener('click', () => callApi(apiUrlMaintenanceOn));
    document.getElementById('apiButtonMaintenanceOff').addEventListener('click', () => callApi(apiUrlMaintenanceOff));    
    document.getElementById('apiButtonReboot').addEventListener('click', () => callApi(apiUrlReboot));
    document.getElementById('apiButtonShutdown').addEventListener('click', () => callApi(apiUrlShutdown));
    </script>
</body>
</html>