RESTful API Guide

The Algo REST API provides flexibility and scalability when integrating Algo IP endpoints with other paging and alerting systems. By using the Algo REST API, devices can trigger or be triggered by unique actions or events.

This guide outlines how to begin using the Algo REST API for an Algo IP endpoint and what calls can be used for device management.

Prerequisites

Make sure the following requirements are met.

  • The Algo endpoint must be using firmware version 3.3 or higher.

  • The time difference between the requestor and the Algo devices should be less than 30 seconds to use standard authentication.

  • Ensure NTP (Network Time Protocol) is enabled on the device. The addresses of custom NTP servers may be configured in the Advanced Settings → Time tab.

  • The target endpoint must have RESTful API access enabled.

  • Check whether the target endpoint requires a password for API access. If yes, include the password information in your API commands. 

Example Use Cases

Remote Button Activation

You can use REST API to remotely activate pre-recorded announcements for urgent situations, such as lockdowns or medical alerts.

For example:

  • A school staff member can call an 8450 SIP extension to make a live announcement during an emergency or important event.

  • A security guard can press a call button to open a gate or trigger an alert.

  • A facility manager can call an 8450 SIP extension to initiate pre-recorded safety or informational messages remotely.

Door Unlock for Building Entry

The REST API can be used to allow a user to unlock a door with the 8063 from a computer program.

School Bell

The REST API can be used to play a bell tone over Algo speakers when classes begin.

Temperature Check

The REST API can be used to trigger Algo visual alerters to flash a color based on a specific event.

Initial Configuration

To allow API control on an Algo device, you must first enable REST API.

You can also set a passcode for REST API to ensure only authorized access is allowed.

Note

If you enable the REST API password, you must include this password in any API command sent to the device.

For example, to access the About page of a device with the default REST API password set to algo, use the following command from a Windows Command Window:

curl -u algo:algo -X GET "http://10.12.123.12/api/info/about".

  1. Enable RESTful API under the Advanced Settings → Admin tab.

  2. Select an Authentication Method. There are three types of authentications:

    Standard (recommended)

    Uses a Hash-based Message Authentication Code (HMAC) with an SHA-256 encoded digest.

    Basic

    Uses Base64 encoding and should only be used over HTTPS.

    None (not recommended)

    Should only be used with extreme care as it provides no authentication.

  3. Enter a RESTful API Password. The default password is algo.

  4. Select Save.

Authentication Requirements

If you have set Authentication Method to Standard, you must authenticate with the API before making any requests.

The authentication process requires generating a valid HMAC signature using the provided RESTful API Password. The device verifies this signature before processing your API command.

Note

If authentication is set to None or Basic, requests signed with Standard Authentication may still succeed because the device does not validate HMAC in those modes.

Standard Authentication Request with a JSON Payload

A standard authentication payload will require generating an HMAC key. This is generated by the REST API password (secret key) and the HMAC input. Generate HMAC with password and HMAC input string as digest using SHA-256.

The hmac input is formatted as: [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce]

Element

Notes

Example

Request method

GET, POST, PUT, or DELETE

POST

Request URI

Must start with a forward slash

/api/controls/tone/start

Content-MD5

Generated separately. Also required for the payload request.

6e43c05d82f71e77c586e29edb93b129

Content-Type

Set as application/json

application/json

Timestamp

Seconds (Unix epoch)

1601312252

Nonce

Random string that is also required for the payload request.

49936

Example HMAC Input (using algo as the secret key)

POST:/api/controls/tone/start:6e43c05d82f71e77c586e29edb93b129:application/json:1601312252:49936

Example HMAC Key

2e109d7aeed54a1cb04c6b72b1d854f442cf1ca15eb0af32f2512dd77ab6b330

Headers

Header Name

Required

Values

Content-Type

Required

application/json

Content-MD5

Required

Same as HMAC input

Authorization

Required

hmac admin:{nonce from HMAC input}:{HMAC key}

Date

Required

day, date month year HH:MM:SS GMT

Example Payload Request

Hypertext Transfer Protocol
 POST /api/controls/ton/start HTTP/1.1\r\n
 Host: 10.0.0.161\r\n
 Accept: */*\r\n
 Transfer-Encoding: chunked\r\n
 Content-Type: application/json\r\n
 Content-Md5: 6e43c05d82f71e77c586e29edb93b129\r\n
 Authorization: hmac admin:1028014788:c450024af4493f9cdf582499456bf58d7e134b161566e764e61bd52d24f759dc\r\n
 Date: Mon, 28 Sep 2020 17:07:18 GMT\r\n
 \r\n
 [Full request URI: http://10.0.0.161/api/controls/tone/start]
 [HTTP request 1/1]
 File data 39 bytes
JavaScript Object Notation: application/json
 Object
  Member Key: path
   String value: page-notif.wav
   Key: path
  Member Key: loop
   False value
   Key: loop

Standard Authentication Request without a JSON Payload

A standard authentication payload will require generating an HMAC key. This is generated by the REST API password (secret key) and the HMAC input. Generate HMAC with password and HMAC input string as digest using SHA-256

The hmac input is formatted as: [request_method]:[request_uri]:[timestamp]:[nonce]

Element

Notes

Example

Request method

GET, POST, PUT, or DELETE

POST

Request URI

Must start with a forward slash

/api/controls/tone/start

Timestamp

Seconds (Unix epoch)

1601312252

Nonce

Random string that is also required for the payload request.

49936

Example HMAC Input (using algo as the secret key)

GET:/api/settings/audio.page.vol:1601312252:49936

Example HMAC Key

c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8

Headers

Header Name

Required

Values

Authorization

Required

hmac admin:{nonce from HMAC input}:{HMAC key}

Date

Required

day, date month year HH:MM:SS GMT

Example Payload Request

Hypertext Transfer Protocol
 GET /api/settings/audio.page.vol HTTP/1.1\r\n
 Host: 10.0.0.161\r\n
 Accept: */*\r\n
 Authorization: hmac admin:881767496:c5b349415bce0b9e1b8122829d32fbe0a078791b311c4cf40369c7ab4eb165a8\r\n
 Date: Mon, 28 Sep 2020 17:07:18 GMT\r\n
 \r\n
 [Full request URI: http://10.0.0.161/api/controls/tone/start]
 [HTTP request 1/1]
 [Response in frame: 304]
Hypertext Transfer Protocol
 HTTP/1.1 200 OK\r\n
 Server: nginx/1.10.3\r\n
 Date: Mon, 28 Sep 2020 17:07:05 GMT\r\n
 Content-Type: application/json\r\n
 Transfer-Encoding: chunked\r\n
 Connection: keep-alive\r\n
 Cache-Control: no-cache, no-store, must-revalidate\r\n
 Pragma: no-cache\r\n
 Expires: 0\r\n
 X-Frame-Options: DENY\r\n
 \r\n
 [HTTP request 1/1]
 [Time since request: 0.242859963 seconds]
 [Request in frame: 297]
 [Request URI: http://10.0.0.161/api/settings/audio.page.vol]
 HTTP chunked response
 File Date: 26 bytes
JavaScript Object Notation: application/json
 Object
  Member Key: audio.page.vol
   String value: -42dB
   Key: audio.page.vol

Basic Authentication Request

A basic authentication payload requires encoding the username and password using Base64. This encoded string is then included in the Authorization header of the HTTP request.

Basic authentication should only be used over secure HTTPS connections, as it transmits credentials in a reversible format.

Headers

Header Name

Required

Values

Authorization

Required

Basic [base64]

Example Payload Request

Hypertext Transfer Protocol
 POST /api/controls/ton/start HTTP/1.1\r\n
 Host: 10.0.0.161\r\n
 Accept: */*\r\n
 Content-Type: application/json\r\n
 Content-Md5: 6e43c05d82f71e77c586e29edb93b129\r\n
 Content-Length: 39\r\n
 Authorization: Basic YWRtaW46YWxnbw==\r\n
 User-Agent: curl/7.58.0\r\n
 \r\n
 [Full request URI: http://10.0.0.161/api/controls/tone/start]
 [HTTP request 1/1]
 [Response in frame: 760]
 File data 39 bytes
JavaScript Object Notation: application/json
 Object
  Member Key: path
   String value: page-notif.wav
   Key: path
  Member Key: loop
   False value
   Key: loop

REST API Calls

The details below describe how Algo REST API can be used to access, manipulate, and trigger actions on Algo IP endpoints on your network through HTTP/HTTPS requests. Requesting systems can interact with Algo devices through a uniform and predefined set of stateless operations.

HTTP/HTTPS requests made to “{device IP address}/URI” with a JSON payload will provide a JSON response. The payload format of all the requests and responses are JSON, except file operations.

A PUT request changes or creates a permanent resource that survives a reboot, while a POST request only controls a device for the current session.

Device Information

Use the following API commands to retrieve or configure specific device parameters.

Retrieve the value of a specific parameter

Get the value of a specific configuration set on the device. Any parameter name that is listed in the Provisioning Parameter Guide that is applicable to the device can be used.

Applicable Products: All

Minimum Firmware Version: 3.3

URI

GET /api/settings/{parameter name}

Parameters

Element

Description

Type

Required

Notes

{parameter name}

Refers to the parameter name for the configuration setting of interest.

String

Required

All values will be retrieved as strings, no matter the parameter or setting.

For the parameter names, see the Parameter column in the following Guides:

Sample Request

GET http://10.12.123.12/api/settings/audio.page.vol

Sample Response

{
    "audio.page.vol": "0dB"
}

Related Links:

Set the value of a specific parameter

Change or set the value of a specific device configuration.

Applicable Products: 8180(G2), 8186, 8190, 8190S, 8301, 8373, 8450

Minimum Firmware Version: 3.3

URI

PUT /api/settings

Parameters

Element

Description

Type

Required

Notes

{parameter name}

Refers to the parameter name for the configuration setting of interest.

String

Required

All values will be retrieved as strings, no matter the parameter or setting.

For the parameter names, see the Parameter column in the following Guides:

Sample Request

PUT http://10.12.123.12/api/settings
{
    "audio.page.vol": "0dB"
}

About the parameter audio.page.vol

The parameter audio.page.vol is available only on the following products: 8190, 8190s, 8186, 8373, 8375, 8180g2, 8301, 8305.

Related Links:

Retrieve a list of all tone files installed on the device

Get the full list of tones available on the device including both pre-loaded tones and custom tones that were uploaded manually.

Applicable Products: All

Minimum Firmware Version: 5.0

URI

GET /api/info/tonelist

Note

The parameter tonelistrefers to the tone files uploaded to the device. All devices are pre-loaded with 10+ tone files.

Response

Element

Description

tonelist

array of tone files

tone file names

The file name of the tone uploaded to the device

Sample Request

GET http://10.12.123.12/api/info/tonelist

Sample Response

{
    "tonelist": [
        "bell-na.wav",
        "bell-uk.wav",
        "buzzer.wav",
        "chime.wav",
        "dogs.wav",
        "gong.wav",
        "page-notif.wav",
        "speech-test.wav",
        "tone-1kHz-max.wav",
        "warble1-low.wav",
        "warble2-med.wav",
        "warble3-high.wav",
        "warble4-trill.wav"
    ]
}

Retrieve the device information from the Status page of the device web interface

Get a list of the device information that is also available on the Status page of the device web interface.

Note

Available status options may vary depending on your device model.

Applicable Products: All

Minimum Firmware Version: 5.4

URI

GET /api/info/status

Response

The response content may vary depending on the device type.

Element

Description

Type

Response

Device Name

The assigned name of the device.

String

{device name}

SIP Registration

The status of SIP registration for the device.

String

  • No Account

  • Attempting to contact server...

  • Successful

  • Deregistered

  • Authenticating...

  • Rejected by server

  • No reply from server

Call Status

The status of calling.

String

  • Idle

  • Ringing

  • Connected

  • Recording Message

  • Playing Delayed Page

Proxy Status

The configured SIP proxy server status.

String

  • Single proxy mode

Provisioning Status

The current status of provisioning.

String

  • Disabled

  • Successful

  • None Found

MAC

The MAC address of the device.

String

The device MAC address

IPv4

If available, the IPv4 address of the device and default gateway.

String

The device IPv4 address

IPv6

If available, the IPv4 address of the device and default gateway.

String

The device IPv6 address

Switch Port ID

The ID of the port on the switch the device is plugged into.

String

Date / Time

The date and time currently used by the device.

String

Day Mon Date HH:MM:SS GMT Year

Current Action

Used for scheduler events (tone, audio stream, or SIP call with tone).

String

Multicast Mode

The multicast mode the device is set to. If the device is in receiver or transmitter mode, the zone it is in will also be displayed when idle.

String

  • Disabled

  • Receiver (Active)

  • Receiver (Idle)

  • Transmitter (Active)

  • Transmitter (Idle)

Volume

The volume set on the device, including dB.

String

Page Volume: ## (##dB)

Relay Input Status

A status of whether or not the relay input is in use.

String

  • Disabled

Temperature:

The temperature of the device.

String

Stand (Docking Station)

The connection status of the 8450 stand.

String

  • Audio: Handset not connected.

  • Button: Idle.

Console

The status of the 8450 console.

String

  • Idle

Sample Request

GET http://10.12.123.12/api/info/status

Sample Response

{
    "Device Name": "pagingadapter-12345",
    "SIP Registration": "Page, No Account;",
    "Call Status": "Idle",
    "Provisioning Status": "None Found",
    "MAC": "00:22:ee:11:11:11",
    "IPv4": "10.10.101.10/1, Gateway: 10.0.1.1",
    "IPv6": "Not Available",
    "Switch Port ID": "name eth0",
    "Date / Time": "Thu Feb  6 17:13:44 GMT 2025",
    "Current Action": "None",
    "Multicast Mode": "Disabled, RTP: 0, PPA: 0, Spk: 0",
    "Volume": "Page Volume: 10 (0dB)",
    "Relay Input Status": "Disabled"
}

Retrieve the device information from the About page of the device web interface

Get a list of the device information that is also available on the About page of the device web interface.

Applicable Products: All

Minimum Firmware Version: 5.4

URI

GET /api/info/about

Response

Element

Description

Type

Product Name

The full name of the product.

String

Firmware Version

The firmware currently installed on the device.

String

MAC Address

The MAC address of the device

String

Hardware Info

The version of the hardware.

String

Manufacturer Certificate

States whether or not the manufacturer’s certificate has been installed

String

Sample Request

GET http://10.12.123.12/api/info/about

Sample Response

{
    "Product Name": "Algo 8301 IP Paging Adapter & Scheduler",
    "Firmware Version": "5.5_beta11",
    "MAC Address": "00:22:ee:11:11:11",
    "Manufacturer Certificate": "Installed"
}

Read Relay Input Status

Retrieve the current status of the relay input.

Applicable Products: All except 8450

Minimum Firmware Version: 3.3

URI

GET /api/info/input.relay.status

Parameters

Element

Description

Type

Required

Notes

input.relay.status

Refers to the overall relay input status.

String

Required

Returns Idle or active state depending on relay condition.

input.relay1.status

Refers to relay input 1 status (8063 only).

String

Optional

Use when reading relay 1 state on 8063.

input.relay2.status

Refers to relay input 2 status (8063 only).

String

Optional

Use when reading relay 2 state on 8063.

Sample Request

GET http://10.12.123.12/api/info/input.relay.status

Sample Response

{
    "input.relay.status": "Idle"
}

************

Device Management

You can manage your device using API commands, such as restoring its settings to factory default and checking for the latest firmware.

Restore the device to factory default

Restore the device to the factory default settings.

Applicable Products: All

Minimum Firmware Version: 5.4

URI

POST /api/settings/action/restore

Sample Request

POST http://10.12.123.12/api/settings/action/restore

Sample Response

{"Restore":"Restoring to default"}

Reboot the device

Reboot the device.

Applicable Products: All

Minimum Firmware Version: 3.3

URI

POST /api/controls/reboot

Sample Request

POST http://10.12.123.12/api/controls/reboot

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Restart Main Application Process

Restart the main application process on the device.

Applicable Products: All

Minimum Firmware Version: 3.3

URI

POST /api/controls/reload

Sample Request

POST http://10.12.123.12/api/controls/reload

Check for the latest firmware available for the device

Get the firmware version the device is currently using.

Applicable Products: All

Minimum Firmware Version: 4.1

URI

POST /api/controls/upgrade/check

Response

Element

Responses

Type

version

  • updated

  • {firmware version}

String

Sample Request

POST http://10.30.238.37/api/controls/upgrade/check

Sample Response

{
    "version": "updated"
}

Upgrade the device with the most recently available firmware

Update the device with the latest firmware available.

Applicable Products: All

Minimum Firmware Version: 4.1

URI

POST /api/controls/upgrade/start

Response

Element

Description

Type

status

  • updated

  • upgrading {firmware version}

  • message

String

url

The URL for the firmware download file

String

Sample Request

POST http://10.30.238.37/api/controls/upgrade/start

Sample Response

{
     "status":"updated"
}

Set the API multicast mode

Applicable to multicast streams controlled by the /api/controls/tone/start command. Use this call to update stream parameters, but not change the configurations directly on the device.

Applicable Products: 8301

Minimum Firmware Version: 5.0

URI

POST /api/state/mcast/update/

Parameters

Element

Description

Type

Required

Notes

mode

The multicast mode of the device

String

Required

Valid values:

  • “sender”

address

Use the IP address used for the command: /api/controls/tone/start/

String

Required

port

Use the port number used for the command: /api/controls/tone/start/

String

Required

type

The multicast transfer type.

String

Required

Valid values:

  • “rtp”

  • “poly”

group

The Poly group being used.

Integer

Optional

Valid values: numbers 1 through 25.

Applicable only when “type”: “poly”

Sample Request

POST http://10.12.123.12/api/state/mcast/update/ 
{
    “mode”: ”sender”, 
    “address”: “224.0.2.60”, 
    “port”: “50002”, 
    “type”: “rtp”, 
    "group": "1"
}

File Management

You can manage files in the system File Manager using API commands, such as listing files, uploading new files, or deleting existing files.

List file directory contents

Get a list of uploaded files available in a specified file folder on the device.

Applicable Products: All except 8039

Minimum Firmware Version: 5.5

Note

A GET or POST call can be used. With a GET command, the payload is included in the URI. With a POST command, the payload is included in the JSON body.

GET URI

GET /api/files/{filepath}

GET Parameters

Element

Default filepaths

Description

{filepath}

certs

This folder is used for server certificates.

debug

This folder is used by Algo support to store files about the device to help troubleshoot.

license

This folder is used to hold licenses.

tones

This folder is used to hold audio files in .WAV or .MP3 format

addressbooks

This folder is used to store paging directories.

This parameter is applicable to 8450 only.

icons

This folder is used to store button icons.

This parameter is applicable to 8450 only.

images

This folder is used to store background images.

This parameter is applicable to 8450 only.

logos

This folder is used to store company logos.

This parameter is applicable to 8450 only.

GET Sample Request

GET http://10.30.238.37/api/files/tones

GET Sample Response

{
  "filelist": [
    "bell-na.wav",
    "bell-uk.wav",
    "buzzer.wav",
    "chime.wav",
    "dogs.wav",
    "gong.wav",
    "page-notif.wav",
    "speech-test.wav",
    "tone-1kHz-max.wav",
    "warble1-low.wav",
    "warble2-med.wav",
    "warble3-high.wav",
    "warble4-trill.wav"
  ]
}

POST URI

POST /api/files/download

Response

Element

Description

filelist

An array of files stored in the file folder

POST Sample Request

POST http://10.12.123.12/api/files/download 
{ 
   "path": "/tones"
}

POST Sample Response

{
    "filelist": [
        "netcap-20250110t194944re4.pcap",
        "netcap-20250110t195031r55.pcap",
        "netcap-20250122t221635rc9.pcap",
        "netcap-20250130t222903r12.pcap",
        "netcap-20250130t231453ra0.pcap",
        "netcap-20250203t194006rf0.pcap",
        "netcap-20250203t194559red.pcap"
    ]
}

Download a file from the device

Select a file to download by specifying the file path.

Applicable Products: All except 8039

Minimum Firmware Version: 5.5

Note

A GET or POST call can be used. With a GET command, the payload is included in the URI. With a POST command, the payload is included in the JSON body.

Parameters

Element

Description

Required

Type

{filepath}

The folder structure to be directed to within the device File Manager

Required

String

{filename}

The file name of interest

Required

String

GET URI

GET /api/files/{filepath}/{filename}

GET Sample Request

GET http://10.30.238.37/api/files/tones/chime.wav

POST URI

POST /api/files/download

POST Sample Request

POST http://10.12.123.12/api/files/download 
{
   "path": "/tones/chime.wav"
}

Add a new file or replace an existing one

When this call is used a new file with the designated file path and file name will be added to the device. If the file path and file name already exist, the existing file will be replaced by the one used in the call.

Applicable Products: All except 8039

Minimum Firmware Version: 5.5

When this call is used a new file with the designated file path and file name will be added to the device. If the file path and file name already exist, the existing file will be replaced by the one used in the call.

URI

PUT /api/files/{filepath}/{filename}

Parameters

Element

Description

Required

Type

{filepath}

The folder structure to be directed to within the device File Manager

Required

String

{filename}

The file name of interest

Required

String

Sample Request

{
  "method": "PUT",
  "url": "http://10.12.123.12/api/files/tones/custom-audio.wav",
  "headers": {
    "Content-Type": "application/octet-stream",
    "Authorization": "Basic base64(username:password)"
  },
  "body": "@C:\\path\\to\\local\\file.wav"
}

Sample Response

None. Go to your device web interface System → File Manager to check whether the file is uploaded successfully.

Delete a file

Select a file to delete by specifying the file path.

Applicable Products: All except 8039

Minimum Firmware Version: 5.5

When this call is used a new file with the designated file path and file name will be added to the device. If the file path and file name already exist, the existing file will be replaced by the one used in the call.

URI

DELETE /api/files/

Parameters

Element

Description

{filepath}

The folder structure to be directed to within the device File Manager

{filename}

The file name of interest

Sample Request

DELETE http://10.12.123.12/api/files/
{
   "path": "/tones/chime.wav"
}

Sample Response

None. Go to your device web interface System → File Manager to check whether the file is deleted successfully.

Door Control

You can lock or unlock a door using API commands.

Lock a door

Control whether the device being called or a secondary connected device locks a door.

Applicable Products: 8039, 8028(G2), 8201, 8063, 8450

Minimum Firmware Version: 3.3

URI

POST /api/controls/door/lock

Parameters

Element

Description

Type

Required

Notes

doorid

Used to indicate whether lock control is to be triggered directly by the device or indirectly by a connected secondary device.

String

Required

Valid values:

  • “netdc1”

  • “local”

Note

  • netdc1 = control the remote network door controller (8063)

  • local = control the local relay

Sample Request

POST http://10.12.123.12/api/controls/door/lock
{
   "doorid": "local"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Unlock a door

Control whether the device being called or a secondary connected device unlocks a door.

Applicable Products: 8039, 8028(G2), 8201, 8063, 8450

Minimum Firmware Version: 3.3

URI

POST /api/controls/door/unlock

Parameters

Element

Description

Type

Required

Notes

doorid

Used to indicate whether lock control is to be triggered directly by the device or indirectly by a connected secondary device.

String

Required

Valid values:

  • “netdc1”

  • “local”

Note

  • netdc1 = control the remote network door controller (8063)

  • local = control the local relay

Sample Request

POST http://10.12.123.12/api/controls/door/unlock
{
   "doorid": "local"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Momentarily unlock a door

Control whether the device being called or a secondary connected device unlocks a door for a specified amount of time.

Applicable Products: 8039, 8028(G2), 8201, 8063, 8450

Minimum Firmware Version: 5.5

URI

POST /api/controls/door/munlock

Parameters

Element

Description

Type

Required

Notes

doorid

Used to indicate whether lock control is to be triggered directly by the device or indirectly by a connected secondary device.

String

Required

Valid values:

  • “netdc1”

  • “local”

duration

The time in seconds that the door should be unlocked for.

String

Required

Note

  • netdc1 = control the remote network door controller (8063)

  • local = control the local relay

Sample Request

POST http://10.12.123.12/api/controls/door/munlock
{
   "doorid": "netdc1",
   "duration": "10"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Audio Control

You can use API commands to control device audio, such as retrieving ambient noise or playing and stopping an audio file.

Retrieve the ambient noise

Get the dB measurement of the ambient noise of the environment the device is in.

Applicable Products: All speakers, 8450

Minimum Firmware Version: 3.3

URI

GET api/info/audio.noise.level

Response

Element

Description

Type

Required

Notes

audio.noise.level

The measured level of ambient noise in dB

String

Required

Will only collect this data if ambient noise compensation is enabled.

Sample Request

GET http://10.12.123.12/api/info/audio.noise.level

Sample Response

{
    "audio.noise.level": "54"
}

Change ambient noise level

Manually update the ambient noise level. This is intended to be used by devices that are controlling volumes but may not directly be in the environment where the noise is. For example, a securely location 8301 set as a multicast transmitter controlling the audio of multiple speakers set as multicast receivers in a warehouse.

Applicable Products: 8190, 8190S, 8410, 8420, 8186, 8188, 8189, 8180G2, 8301

Minimum Firmware Version: 5.4

URI

POST /api/controls/noise/update

Parameters

Element

Description

Type

Required

level

The measured level of ambient noise in dB

String

Required

Sample Request

POST http://10.12.123.12/api/controls/noise/update
{
   "level": "50"
}

Sample Response

None. You can use an API command to get the ambient noise level to see whether the change is made.

Play default test tone

Play the default tone assigned to the device.

Applicable Products: 8190, 8190s, 8410, 8420, 8300, 8039, 8028g2, 8186, 8373, 8188, 8189, 8180g2, 8301, 8201, 8450

Minimum Firmware Version: 5.4

URI

POST /api/controls/test/start

Sample Request

POST http://10.12.123.12/api/controls/test/start

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Loop default test tone

Play the default tone assigned to the device on a loop until a separate call stops the loop.

Applicable Products: 8190, 8190s, 8410, 8420, 8300, 8039, 8028g2, 8186, 8373, 8188, 8189, 8180g2, 8301, 8201, 8450

Minimum Firmware Version: 5.4

URI

POST /api/controls/test/loop

Sample Request

POST http://10.12.123.12/api/controls/test/loop

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Stop default test tone

Stop playing the default tone assigned to the device.

Applicable Products: 8190, 8190s, 8410, 8420, 8300, 8039, 8028g2, 8186, 8373, 8188, 8189, 8180g2, 8301, 8201, 8450

Minimum Firmware Version: 5.4

URI

POST /api/controls/test/stop

Sample Request

POST http://10.12.123.12/api/controls/test/stop

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Play or loop a selected tone

Play a selected tone uploaded to the device once or on a loop.

Applicable Products: All speakers, paging adapters, 8028(G2), 8201, 8039, 8450

Minimum Firmware Version: 5.4

URI

POST /api/controls/tone/start

Parameters

Element

Description

Type

Required

Notes

path

The file name of the tone to be played

string

Required

Default valid values:

  • bell-na.wav

  • bell-uk.wav

  • buzzer.wav

  • chime.wav

  • dogs.wav

  • gong.wav

  • page-notif.wav

  • tone-1kHz-max.wav

  • warble1-low.wav

  • warble2-med.wav

  • warble3-high.wav

  • warble4-trill.wav

Note: Any file name stored under System → File Manager → tones folder is a valid value.

loop

Set the tone file to loop

boolean

Required

Valid values:

  • “true”

  • “false”

mcast

Configure the device to multicast transmit and play a tone or loop a tone on a receiving device.

boolean

Optional

Valid values:

  • “true”

  • “false”

Multicast must be on to use. If multicast is turned on via /mcast/update at any time, this call will default to these settings. If multicast is only configure via web interface, this call will default to the web interface settings.

Note: For firmware version 5.5 and earlier, this parameter is available only on 8301 devices.

playback

Whether the receiving endpoint plays the multicast message

string

Optional

Valid values:

  • “true”

  • “false”

Note: For firmware version 5.5 and earlier, this parameter is available only on 8301 devices.

state

The multicast parameters.

string

Optional

Note: For firmware version 5.5 and earlier, this parameter is available only on 8301 devices.

mode

The multicast mode of the device

string

Optional

Valid values:

  • “sender”

address

The IP address of the receiving device.

string

Optional

port

The port used by the receiving device.

string

Optional

type

The multicast transfer type.

string

Optional

Valid values:

  • “poly”

group

The Poly group being used.

integer

Optional

Valid values: numbers 1 through 25.

Applicable only when “type” is set as “poly”.

Sample Request

POST http://10.12.123.12/api/controls/tone/start
{
  "path": "chime.wav",
  "loop": true,
  "mcast": true,
  "playback": false,
  "state": {
    "mode": "sender",
    "address": "<address>",
    "port": "<port>",
    "type": "poly",
    "group": 1
  }
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Stop tone on firmware 5.5

Stop the looping tone.

Applicable Products: All speakers, paging adapters, 8028(G2), 8201, 8039, 8450

URI

POST /api/controls/tone/stop

Sample Request

POST http://10.12.123.12/api/controls/tone/stop

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Stop a selected tone on firmware 5.4

Stop the looping of a selected tone. For firmware 5.4, you must include a payload in the API request.

Applicable Products: All speakers, paging adapters, 8028(G2), 8201, 8039, 8450

URI

POST /api/controls/tone/stop

Parameters

Element

Description

Type

Required

path

The file name of the tone being played

string

Required

Sample Request

POST http://10.12.123.12/api/controls/tone/stop
{
	"path": "chime.wav",
}

Start listening to a direct audio stream

Open the path to an audio stream to listen.

Applicable Products: All

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/rx/start

Parameters

Element

Description

Type

Required

port

Port to listen.

string

Required

Sample Request

POST http://10.12.123.12/api/controls/rx/start
{
	"port": "5001",
}

Stop listening to a direct audio stream

Close the path to an audio stream to stop listening.

Applicable Products: All

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/rx/stop

Sample Request

POST http://10.12.123.12/api/controls/rx/stop

Call Control

You can use API commands to control calls, such as starting or stopping a SIP call.

Call a phone extension and play an audio file

Call an assigned phone extension and play an audio file. The extension can be used to broadcast the audio file via multicast for a set amount of time if multicast is configured.

Applicable Products: All speakers, 8301, 8450

Minimum Firmware Version: 3.3

URI

POST /api/controls/call/start

Parameters

Element

Description

Type

Required

Notes

extension

The phone extension to call.

String

Required

tone

The file name of the tone to play.

String

Required

Used to call and play a tone.

interval

Specify how long to wait (in seconds) before the tone plays again after it ends.

String

Optional

maxdur

The total time (in seconds) to play the tone on a repeated loop.

String

Optional

Note

If /api/controls/tone/start is used before /api/state/mcast/update, the tone will play using the web interface settings.

Sample Request

POST http://10.12.123.12/api/controls/call/start
{
	"extension": "123",
	"tone": "chime.wav",
	"interval": "3",
	"maxdur": "60"
}

End a call to a phone extension

End a call to a phone extension.

Applicable Products: 8301, 8450

Minimum Firmware Version: 3.3

URI

POST /api/controls/call/stop

Sample Request

POST http://10.12.123.12/api/controls/call/stop

Initiate a one-way page call to receive an audio stream from a specified extension

Open an extension to be able to receive an audio stream. The audio stream must be configured separately.

Applicable Products: All Speakers, 8450

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/call/page

Parameters

Element

Description

Type

Notes

extension

The phone extension to call

String

Sample Request

POST http://10.12.123.12/api/controls/call/page
{
	"extension": "123"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Relay Control

You can use API commands to control relay input and output. For example, you can check the status of a relay input terminal or activate a relay output..

Retrieve the status of the relay input terminal

Get the status of a relay input terminal to see if it is in use on the device.

Applicable Products: 8301, 8305, 8186, 8188, 8189, 8180, 8190, 8190S, 8410, 8420, 8138, 8128

Minimum Firmware Version: 3.3

URI

GET api/info/input.relay.status

Response

Element

Description

Type

Notes

input.relay.status

States whether or not the relay is connected and actively in use.

String

Responses include:

  • “idle”

  • “active”

  • “Disabled”

If active, will also describe the activity.

Sample Request

GET http://10.12.123.12/api/info/input.relay.status

Sample Response

{
    "input.relay.status": "Disabled"
}

Retrieve the status of an 8063 input terminal

Get the status of an input terminal to see if it is in use on the device.

Applicable Products: 8063

Minimum Firmware Version: 4.1

URI

GET api/info/input.relay1.status

or

GET api/info/input.relay2.status

Response

Element

Description

Type

Notes

input.relay{number}.status

States whether or not the relay is connected and actively in use.

String

Responses include:

  • “idle”

  • “active”

  • “Disabled”

If active, will also describe the activity.

Sample Request

GET http://10.12.123.12/api/info/input.relay1.status

Sample Response

{
    "input.relay1.status": "Idle"
}

Enable the 8063 24V AUX Out Relay

Enable the 24V AUX out relay on the 8063.

Applicable Products: 8063

Minimum Firmware Version: 5.0

URI

POST api/controls/24v/enable

Sample Request

POST http://10.12.123.12/api/controls/24v/enable

Disable the 8063 24V AUX Out Relay

Disable the 24V AUX out relay on the 8063.

Applicable Products: 8063

Minimum Firmware Version: 5.0

URI

POST api/controls/24v/disable

Sample Request

POST http://10.12.123.12/api/controls/24v/disable

Enable the 8063 Output Relay

Enable the output relay on the 8063.

Applicable Products: 8063

Minimum Firmware Version: 5.0

URI

POST api/controls/relay/enable

Sample Request

POST http://10.12.123.12/api/controls/relay/enable

Enable the 8063 Output Relay Momentarily

Enable the output relay on the 8063.

Applicable Products: 8063

Minimum Firmware Version: 5.6

URI

POST api/controls/relay/menable

Parameters

Element

Description

Type

Required

duration

The time (in seconds) the relay should stay enabled

Int

Required

Sample Request

POST http://10.12.123.12/api/controls/relay/menable
{
	"duration": 15
}

Disable the 8063 Output Relay

Disable the output relay on the 8063.

Applicable Products: 8063

Minimum Firmware Version: 5.0

URI

POST api/controls/relay/disable

Sample Request

POST http://10.12.123.12/api/controls/relay/disable

Screen Control

You can use API commands to control content displaying on the scree, such as displaying an image, or adding a strobe light to the screen. You can also add strobe light to a screen.

Display a single image on the device screen

Display one static image on the device screen.

Applicable Products: 8410, 8420

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/screen/start

Parameter

Element

Description

Type

Required

Notes

type

The type of background to display

String

Required

Set as “image”

image1

The file name of the image

String

Required

Sample Request

POST http://10.12.123.12/api/controls/screen/start
{
	"type": "image",
	"image1": "school.jpeg"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Related Links:

Display scrolling text over an image on the device screen

Display scrolling text on top of a static image on the device screen.

Applicable Products: 8410, 8420

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/screen/start

Parameter

Element

Description

Type

Required

Notes

type

The type of background to display

String

Required

Set as “image”

image1

The file name of the image

String

Required

text1

The text to be displayed on the device

String

Required

textColor

The color of the text

String

Optional

Valid values:

  • SVG color name

  • HEX code

For more information, see Scalable Vector Graphics Colors Hexadecimal.

Default= “black”

textFont

The font of the text

String

Optional

Valid values include:

  • “acumin”

  • “bookman”

  • “din”

  • “inter”

  • “nixie”

  • “overpass”

  • “roboto”

Default= “inter”

textPosition

Where the text should be displayed on the screen

String

Optional

Valid values include: “

  • “top”

  • “middle”

  • “bottom”

Default= “bottom”

textScroll

Turn text scroll on or off

String

Required

Valid values include:

  • “true”

  • “false”

textScrollSpeed

The speed at which the text scrolls

String

Optional

Valid values include:

  • “1”

  • “2”

  • “3”

  • “4”

  • “5”

Default= “1”

textSize

The size of the text

String

Optional

Valid values include:

  • “small”

  • “medium

  • “large”

Default=”large”

Sample Request

POST http://10.12.123.12/api/controls/screen/start
{
	"type": "image",
	"image1": "school.jpeg",
	"text1": "Class is in session",
	"textColor": "forestgreen",
	"textFont": "inter",
	"textPosition": "middle",
	"textScroll": true
	"textScrollSpeed": "3",
	"textSize": "medium"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Related Links:

Display a clock on the device screen

Display a digital or analog clock on the device screen.

Applicable Products: 8410, 8420

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/screen/start

Parameter

Element

Description

Type

Required

Notes

type

The type of clock to display

String

Required

Valid values:

  • “digitalClock”

  • “analogClock”

clockFormat

Display the time in a 12h or 24h format.

String

Optional

Use if type=digitalClock

Valid values:

  • “12h”

  • “24h”

Default= “24h”

clockSeconds

clockSeconds

Boolean

Optional

Use if type=digitalClock

Default= “false”

clockSecondsAnalog

Enable or disable displaying clock seconds

Boolean

Optional

Use if type= analogClock

Default= “true”

clockBgColor

The background color of the clock

String

Optional

Use if type=digitalClock

Valid values:

  • SVG color name

  • HEX code

clockFgColor

The foreground color of the clock

String

Optional

Use if type=digitalClock

Valid values:

  • SVG color name

  • HEX code

Default= “white”

analogBgColor

The background color of the clock

String

Optional

Use if type=analogClock

Valid values:

  • SVG color name

  • HEX code

analogFgColor

The foreground color of the clock

String

Optional

Use if type=analogClock

Valid values:

  • SVG color name

  • HEX code

Default= “black”

analogSecondsColor

The color of the seconds hand on the analog clock

String

Optional

Use if type=analogClock

Valid values:

  • SVG color name

  • HEX code

clockFont

The font of the clock text

String

Optional

Use if type=digitalClock

Valid values include:

  • “acumin”,

  • “bookman”,

  • “din”,

  • “inter”,

  • “nixie”,

  • “overpass”,

  • “roboto”

Default= “inter”

clockBgImage

The file name of the background image to use behind the clock if needed.

String

Optional

Use if type=digitalClock

Sample Request for Digital Clock

POST http://10.12.123.12/api/controls/screen/start
{
	"type": "digitalClock”,
	"clockFormat": "12h",
	"clockSeconds": "1",
	"clockBgColor": "navy",
	"clockFgColor": "beige",
	"clockFont": "inter",
	"clockBgImage": "school-entrance.jpeg"
}

Sample Request for Analog Clock

POST http://10.12.123.12/api/controls/screen/start
{
	"type": "analogClock”	
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Related Links:

Display flashing images on the device screen

Display multiple images one after another on the device screen.

Applicable Products: 8410, 8420

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/screen/start

Parameter

Element

Description

Type

Required

Notes

type

The type of background to display

String

Required

Set as “blitz”

image1

The image file name to use

String

Required

image2

The image file name to use

String

Optional

…

The image file name to use

String

Sample Request

POST http://10.12.123.12/api/controls/screen/start
{
	"type": "blitz",
	"image1": "school_entrance.jpeg",
	"image2": "school_logo.jpeg"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Related Links:

Display a slideshow on the device screen Using file names

Select a pre-configured slides to display on the screen by specifying file names.

Applicable Products: 8410, 8420

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/screen/start

Parameter

Element

Description

Type

Required

Notes

duration

Duration of each slide in seconds

Integer

Required

slideNames

The file names of the slides to display in the slideshow

Comma-separated values as a string

Required

Format is: “slide1, slide2, slide3, …”

overrideStrobe

Use specified strobe parameters for the slideshow instead of the strobe parameters of each individual slide.

Boolean

Required

Valid values include:

  • “true”

  • “false”

Sample Request

POST http://10.12.123.12/api/controls/screen/start
{
	"duration": 10,
	"slideNames": "slide1, slide2, slide3",
	"overrideStrobe": true
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Related Links:

Add strobe light to a screen

You can use the parameters below to add a strobe light to a screen. These parameters work with the following commands:

Element

Description

Type

Required

Notes

strobeFlash

The strobe flash pattern to use

Integer

Required

Valid values: See Algo Strobe Light Pattern Reference Guide

strobeColor

The color to display on the strobe

String

Required

Valid values:

  • "red”

  • "blue”

  • “green”

  • “amber”

strobeColor2

The second color to display on the strobe if desired

String

Required

Valid values:

  • "red”

  • "blue”

  • “green”

  • “amber”

strobeLedlvl

The brightness of the strobe light.

String

Required

Valid values are between 0-255.

Related Links

Stop a screen pattern and return the screen to default

Return a screen to the default setting.

Applicable Products: 8410, 8420

Minimum Firmware Version: 5.3.4

URI

POST /api/controls/screen/stop

Sample Request

POST http://10.12.123.12/api/controls/screen/stop

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Strobe Lights

You can control strobe lights using API commands, such as starting or stopping a light.

Start a strobe light

Turn on a strobe light.

Applicable Products: 8128(G2), 8138, 8190S, 8450

Minimum Firmware Version: 3.3

URI

POST /api/controls/strobe/start

Parameters

Element

Description

Type

Notes

pattern

The number of the pattern set.

Integer

Valid values: See Algo Strobe Light Pattern Reference Guide

color1

The color to set the strobe

String

Valid values:

  • "red”

  • "blue”

  • “green”

  • “amber”

color2

The second color for the strobe to use if the pattern uses two colors.

String

Only applicable to 8138.

Valid values:

  • "red”

  • "blue”

  • “green”

  • “amber”

ledlvl

The brightness of the strobe light.

String

Valid values are between 0-255.

Related Links

Sample Request

POST http://10.12.123.12/api/controls/strobe/start
{
	"pattern": 1,
	"color1": "red",
	"color2": "blue",
	"ledlvl": "100"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

Stop a strobe light

Turn off a strobe light.

Applicable Products: 8128(G2), 8138, 8190S, 8450

Minimum Firmware Version: 3.3

URI

POST /api/controls/strobe/stop

Sample Request

POST http://10.12.123.12/api/controls/strobe/stop

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

8450 Button Control

You can use API commands to activate or deactivate 8450 buttons. This lets you trigger or stop the actions linked to those buttons.

Activate a 8450 Button

Activate a button on a 8450 screen. This triggers the action associated with that button.

Applicable Products: 8450

Minimum Firmware Version: 5.6

URI

POST /api/controls/console/button/activate

Parameters

Element

Description

Type

Required

Notes

id

The button identifier.

string

Required

Make sure it matches the one configured for the button on its configuration screen.

Sample Request

POST http://10.12.123.12/api/controls/console/button/activate
{
"id":"weather-incident"
}

Sample Response

None. The observable outcome is whether the device performs the requested action or not.

About duplicated button identifiers

In case of duplicated button identifiers, the action priority is determined by its hosting button or screen, in the following order:

  1. Action button (single press)

  2. Action button (double press)

  3. Home screen

  4. Emergency screen

  5. Emergency Paging screen

  6. Paging screen

  7. Custom screens 1 → 20 (The custom screen with the lower number takes priority)

 

Stop Ongoing Actions on 8450

Stop active events, such as paging, SIP calls, or tone playback.

Applicable Products: 8450

Minimum Firmware Version: 5.6

URI

 POST /api/controls/console/event/stop

Parameters

Element

Description

Type

Required

Notes

type

The event type.

string

Required

Valid values:

  • "all" : Stop all ongoing events.

  • “emergency” : Stop active emergency paging.

  • “nonEmergency” : Stop activeNon-Emergency paging.

  • “call” : Stop an active SIP call.

  • “pageMic” : Stop live paging through 8450 microphone.

  • “pageTone” : Stop onoging tones or pre-recorded announcements.

Sample Request

POST http://10.12.123.12/api/controls/console/event/stop
{
"type":"all"
}

Sample Response:

Stopped 1 event(s).

 

List active events on 8450

List active events on the 8450, such as ongoing paging, SIP calls, or tone playback.

Applicable Products: 8450

Minimum Firmware Version: 5.6

URI

 GET /api/console/event/status

Parameters

Element

Description

Type

Required

Notes

type

The event type.

string

Required

Valid values:

  • "all" : Stop all ongoing events.

  • “emergency” : Stop ongoing emergency paging.

  • “nonEmergency” : Stop ongoing Non-Emergency paging.

  • “call” : Stop ongoing SIP calls.

  • “pageMic” : Stop live paging through 8450 microphone.

  • “pageTone” : Stop onoging tones or pre-recorded announcements.

Sample Request

GET http://10.12.123.12/api/console/event/status

Sample Response:

{"active":[ 

               {"type":"emergency"}, 

               {"type":"pageMic"} 

]}