---
title: "RESTful API Guide"
slug: "restful-api-guide"
updated: 2026-09-24T18:24:47Z
published: 2026-09-24T18:24:47Z
canonical: "docs.algosolutions.com/restful-api-guide"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algosolutions.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

#### **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.

![](https://cdn.document360.io/f6f5e62d-d280-487f-9da7-5926ffd53b5f/Images/Documentation/api-door-unlock.png)

#### **School Bell**

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

![](https://cdn.document360.io/f6f5e62d-d280-487f-9da7-5926ffd53b5f/Images/Documentation/api-school-bell.png)

#### **Temperature Check**

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

![](https://cdn.document360.io/f6f5e62d-d280-487f-9da7-5926ffd53b5f/Images/Documentation/AIP-Blog-Diagrams-v02C-20241125.png)

**Remote Button Activation**

The REST API can be used to control Algo 8450 buttons to play pre-recorded announcements for urgent situations, such as lockdowns or medical alerts.

![](https://cdn.document360.io/f6f5e62d-d280-487f-9da7-5926ffd53b5f/Images/Documentation/image(455).png)

## 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]
> 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:
> 
> curl -u admin:algo -X GET "[https://10.12.123.12/api/info/about](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 authentication:

| 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) | It should only be used with extreme care as it provides no authentication. |
3. Enter a **RESTful API Password**. The default password is *algo*. ![](https://cdn.document360.io/f6f5e62d-d280-487f-9da7-5926ffd53b5f/Images/Documentation/image(158).png)
4. Select **Save**.

## Authentication Requirements

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

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

### Standard Authentication Request with a JSON Payload

A standard authentication payload will require generating an HMAC digest. 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 digest must be lowercase hex-encoded.

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 Digest**

`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, DD Mon YYYY HH:MM:SS GMT |

**Example Payload Request**

```json
Hypertext Transfer Protocol
 POST /api/controls/tone/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: https://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 digest. 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 digest must be lowercase hex-encoded.

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/settings/[audio.page](http://audio.page).vol |
| 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 Digest**

`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**

```json
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: https://10.0.0.161/api/settings/audio.page.vol]
 [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: https://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**

```json
Hypertext Transfer Protocol
 POST /api/controls/tone/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: https://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 the Algo REST API can 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 to “{device IP address}/URI” with a JSON payload will provide a JSON response. The payload format of all the requests and responses is JSON, except for 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.

> [!NOTE]
> Note
> 
> If a configuration parameter value in an API command differs from the value set in the device’s web interface, the API setting takes precedence.
> 
> For example, if the web interface configures the device as a multicast receiver, but the API command sets it as a multicast transmitter, the device will operate as a multicast transmitter when processing the API request.

### 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 parameter on the device. Any parameter name listed in the Provisioning Parameter Guide 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: - [Speaker Provisioning Guide](https://docs.algosolutions.com/v1/docs/speaker-provisioning-guide) - [Paging Adapter Provisioning Guide](https://docs.algosolutions.com/v1/docs/paging-adapter-provisioning-guide) - [Intercom Provisioning Guide](https://docs.algosolutions.com/v1/docs/intercom-provisioning-parameters) |

**Sample Request**

`GET https://10.12.123.12/api/settings/audio.page.vol`

**Sample Response**

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

**Related Links:**

- [Speaker Provisioning Guide](https://docs.algosolutions.com/v1/docs/speaker-provisioning-guide)
- [Paging Adapter Provisioning Guide](https://docs.algosolutions.com/v1/docs/paging-adapter-provisioning-guide)
- [Intercom Provisioning Guide](https://docs.algosolutions.com/v1/docs/intercom-provisioning-parameters)

#### Set the value of a specific parameter

Change the value of a specific configuration parameter.

**Applicable Products**: All

**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: - [Speaker Provisioning Guide](https://docs.algosolutions.com/v1/docs/speaker-provisioning-guide) - [Paging Adapter Provisioning Guide](https://docs.algosolutions.com/v1/docs/paging-adapter-provisioning-guide) - [Intercom Provisioning Guide](https://docs.algosolutions.com/v1/docs/intercom-provisioning-parameters) |

**Sample Request**

```json
PUT https://10.12.123.12/api/settings
{
    "audio.page.vol": "0dB"
}
```

**Related Links:**

- [Speaker Provisioning Guide](https://docs.algosolutions.com/v1/docs/speaker-provisioning-guide)
- [Paging Adapter Provisioning Guide](https://docs.algosolutions.com/v1/docs/paging-adapter-provisioning-guide)
- [Intercom Provisioning Guide](https://docs.algosolutions.com/v1/docs/intercom-provisioning-parameters)

#### 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]
> Note
> 
> The parameter `tonelist`refers 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 https://10.12.123.12/api/info/tonelist`

**Sample Response**

```json
{
    "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]
> Note
> 
> Available status 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 |
| Next Scheduled Action | The next scheduled action. | String | - When no action is scheduled, it displays “No Actions Scheduled”. - When there is an action scheduled, it displays action information, including: - {Schedule Name} - {Action} - {Date} - {Time} - {Tone Name} (If the **Action** is **SIP Call with Tone**) |
| Next Scheduled Event | The next scheduled event. | String | - When no event is scheduled, it displays “No Events Scheduled”. - When there is an event scheduled, it displays event information, including: - {Schedule Name} - {Date} - {Time} - {Audio Name} |
| Proxy Status | The configured SIP proxy server status. | String | - When SIP **Server Redundancy** is not enabled, the status displays: Single proxy mode. - When SIP **Server Redundancy** is in use, the status displays in this format: Active: {}, PRI:{} , BK1: {}, BK2:{}. For example: "Active: Primary, PRI: Up, BK1: Down: BK2: Not Configured". |
| Provisioning Status | The current status of provisioning. | String | - Disabled - Successful - None Found |
| MAC | The MAC address of the device. | String | The device’s MAC address |
| IPv4 | If available, the IPv4 address of the device and the default gateway. | String | The device’s IPv4 address |
| IPv6 | If available, the IPv6 address of the device and the default gateway. | String | The device's IPv6 address |
| Switch Port ID | The ID of the port on the switch the device is plugged into. | String | {Port ID} |
| 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 | - None - Streaming Audio |
| 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 active. | String | - Disabled - Receiver (Active) - Receiver (Idle) - Transmitter (Active) - Transmitter (Idle) |
| OAuth Profile Status | The status of OAuth profiles | String | - Active - {Error message} |
| Volume | The volume set on the device, including dB. | String | Page Volume: ## (##dB) |
| Relay Input Status | The status of relay input. | String | - When relay input is enabled, it displays information such as the active state, configured mode, action, or whether or not a tamper is detected. - When the relay input is not enabled, it displays “Disabled”. |
| Temperature | The temperature of the device. | String | {Temperature} |
| Stand (Docking Station) | The connection status of the 8450 stand. | String | - Audio: - Handset not connected - Handset connected - Active - Handset connected - Idle |
| Panic Button Status | The status of each configured panic button, including its location, description, and current state. | String | - {Location} - {Description} - {Status} |
| Virtual Panic Button Status | The status of each configured virtual panic button, including its location, description, and current state. | String | - {Location} - {Description} - {Status} |
| Action Button | The status of the Action Button | String | - Pressed - Idle |
| Console | The status of the 8450 console. | String | - Idle - Paging with Tone Active - Remote Screen with Tone Active - Emergency Alert Active - Remote Emergency Alert Active - Call Active - Paging with Mic Active - Delayed Paging with Mic Active - Playing Media - Audio Recording Active |
| Weather Status | The status of the configured weather service and the weather location | String | - Active |
| Last Weather Update | The date and time of the most recent weather update. | String | {Date time} |

**Sample Request**

`GET https://10.12.123.12/api/info/status`

**Sample Response**

```json
{
    "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 https://10.12.123.12/api/info/about`

**Sample Response**

```json
{
    "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 the 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**

```plaintext
GET https://10.12.123.12/api/info/input.relay.status
```

**Sample Response**

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

### Device Management

You can manage your device using API commands, such as restoring its factory default settings 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 https://10.12.123.12/api/settings/action/restore`

**Sample Response**

```json
{"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 https://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**

```plaintext
POST https://10.12.123.12/api/controls/reload
```

#### Check for the latest firmware available for the device

Check for the latest firmware available for the device.

**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 https://10.30.238.37/api/controls/upgrade/check`

**Sample Response**

```json
{
    "version": "updated"
}
```

#### Upgrade the device with the most recently available firmware

Check the Algo provisioning server for the latest firmware version and upgrade to that version.

**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 https://10.30.238.37/api/controls/upgrade/start`

**Sample Response**

```json
{
     "status":"updated"
}
```

#### Set the 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**: All except 8450

**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**

```json
POST https://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, uploading new files, or deleting existing files.

#### List the file folder contents or download a file

You can use `GET /api/files/{filepath}` or `POST /api/files/download` to do the following:

- Retrieve a list of files available in a specified folder within the device's **System** → **File Manager**.

You must specify the target file folder name in the request.
- Download a file that is available in the device's **System** → **File Manager**.

You must specify the target file name in the request.

> [!NOTE]
> Note
> 
> With a **GET** command, the payload is included in the URI. With a **POST** command, the payload is included in the JSON body.

**Applicable Products**: All except 8039

**Minimum Firmware Version**: 5.5

**URI**

- `GET /api/files/{filepath or filename}`
- `POST /api/files/download`

**Parameters**

| Element | Description | Type | Required | Valid Values |
| --- | --- | --- | --- | --- |
| {filepath} | The name of the folder from which to list the file contents. | string | Required if you want to get the file directory content. | Valid values: The name of any file that exists in your device's File Manager. |
| {filename} | The name of the file to be downloaded. | string | Required if you want to download a file. | Valid values: The name of any file that exists in your device's File Manager. |

**GET Sample Request for Listing a File Folder Contents**

`GET https://10.30.238.37/api/files/tones`

**GET Sample Response for Listing a File Folder Contents**

```json
{
  "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 Sample Request for Listing a File Folder Contents**

```json
POST https://10.12.123.12/api/files/download 
{ 
   "path": "/tones"
}
```

**POST Sample Response for Listing a File Folder Contents**

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

**GET Sample Request for Downloading a File**

`GET https://10.30.238.37/api/files/tones/chime.wav`

**POST Sample Request for Downloading a File**

```json
POST https://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

**URI**

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

**Parameters**

| Element | Description | Required | Type |
| --- | --- | --- | --- |
| {filepath} | The folder structure to be directed to within the device's **File Manager.** | Required | String |
| {filename} | The file name. | Required | String |

**Sample Request**

Here is an example using Postman to send this command:

| Item | Configuration |
| --- | --- |
| Method | PUT |
| URL | [https://10.12.123.12/api/files/tones/custom-audio.wav](http://10.12.123.12/api/files/tones/custom-audio.wav) |
| Auth | **Basic Auth** **Username**: admin **Password**: algo > [!NOTE] > Note > > For legacy compatibility, username `algo` is also supported. |
| Headers | **Key**: Content-Type **Value**: Application/octet-stream |
| Body | **Binary** Select the target audio file from your local drive. |

![](https://cdn.document360.io/f6f5e62d-d280-487f-9da7-5926ffd53b5f/Images/Documentation/Screenshot 2025-09-29 150029 (1).png)

**Sample Response**

None. Go to your device's web interface **System** → **File Manager** to check whether the file has been 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, the specified file will be deleted from the device.

**URI**

`DELETE /api/files/`

**Parameters**

| Element | Description |
| --- | --- |
| {filepath} | The folder structure to be directed to within the device's **File Manager**. |
| {filename} | The file name. |

**Sample Request**

```json
DELETE https://10.12.123.12/api/files/
{
   "path": "/tones/chime.wav"
}
```

**Sample Response**

None. Go to your device’s web interface **System** → **File Manager** to check whether the file has been deleted successfully.

#### MD5 Checksum Query API

Retrieves the MD5 checksum for a specified file in the **File Manager** to support file integrity and version validation.

**Applicable Products**: All

**Minimum Firmware Version**: 5.7

**URI**

`GET /api/file-md5sum/<filepath>/<filename>`

**Parameters**

| **Element** | Description | Format / Type | Required |
| --- | --- | --- | --- |
| `filepath` | The target file folder in **System** → **File Manager**. | String | Required |
| `filename` | The target file name, including the file extension. | String | Required |

**Sample Request:** Query the MD5 checksum of a file.

```plaintext
curl -X GET \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        https://10.11.12.123/api/file-md5sum/tones/chime.wav
```

**Example Response:**

```json
{"md5sum":"6267f951c9b28c83ca55972823f3d50e"}
```

### 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

**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]
> Note
> 
> - netdc1: Control the remote network door controller (8063)
> - local: Control the local relay.

**Sample Request**

```json
POST https://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

**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]
> Note
> 
> - netdc1: Control the remote network door controller (8063)
> - local: Control the local relay

**Sample Request**

```json
POST https://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 duration.

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

**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]
> Note
> 
> - netdc1: Control the remote network door controller (8063)
> - local: Control the local relay

**Sample Request**

```json
POST https://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**

```json
GET https://10.12.123.12/api/info/audio.noise.level
```

**Sample Response**

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

#### Change the ambient noise level

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

**Applicable Products**: 8190, 8190S, 8516, 8410, 8420, 8186, 8450, 8188, 8189, 8196, 8197, 8198, 8199, 8180g2, 8301, 8305, 8312, 8507

**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**

```json
POST https://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 has been made.

#### Play the default test tone or turn on a strobe light

Trigger a test tone on supported audio devices and activate a strobe light on visual alert devices.

**Applicable Products**:

- 8190, 8190S, 8300, 8039, 8028 (G2), 8186, 8373, 8375, 8188, 8189, 8196, 8197, 8198, 8199, 8180(G2), 8301, 8305, 8312, 8201, 8203: Play the default test tone.
- 8128 (G2), 8138: Start a steady strobe light for five seconds.
- 8410, 8420: Start a steady strobe light for five seconds and play the test tone once.

**Minimum Firmware Version**: 5.4

**URI**

`POST /api/controls/test/start`

**Sample Request**

```json
POST https://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 the default test tone or turn on a strobe light

Trigger a test tone loop on supported audio devices and activate a steady strobe light on visual alert devices.

**Applicable Products**:

- 8190, 8190S, 8516, 8300, 8039, 8410, 8420, 8028 (G2), 8186, 8373, 8375, 8188, 8189, 8196, 8197, 8198, 8199, 8180 (G2), 8301, 8305, 8312, 8201, 8203, 8507

: Loop playing the default test tone.
- 8128 (G2), 8138: Start a steady strobe light.
- 8410, 8420: Start a steady strobe light and loop playing the test tone.

**Minimum Firmware Version**: 5.4

**URI**

`POST /api/controls/test/loop`

**Sample Request**

```json
POST https://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 the default tone or strobe light

Stop the default test tone on supported Algo audio devices and turn off the test strobe light on visual alert devices.

**Applicable Products**:

- 8190, 8190S, 8300, 8039, 8028 (G2), 8186, 8373, 8375, 8188, 8189, 8196, 8197, 8198, 8199, 8180 (G2), 8301, 8305, 8312, 8201, 8203: Stop default test tone.
- 8128 (G2), 8138: Stop the test strobe light.
- 8410, 8420: Stop the strobe light and test tone.

**Minimum Firmware Version**: 5.4

**URI**

`POST /api/controls/test/stop`

**Sample Request**

```json
POST https://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, 8203, 8039

**Minimum Firmware Version**: 5.4

**URI**

`POST /api/controls/tone/start`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| duration | How long the audio plays (in seconds). | Integer | Optional | This parameter is available only on firmware version 5.7 and later. |
| 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**: The file name of any file stored under the **System → File Manager → tones** folder is a valid value. |
| interval | When audio file looping is enabled (`loop = true`), specify the pause time between playbacks, in seconds. | Integer | Optional |  |
| 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 configured via the 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” Applicable only when “mcast” is set as “true” |
| address | The IP address of the multicast zone. | string | Optional | Applicable only when “mcast” is set as “true” |
| port | The port of the multicast zone. | string | Optional | Applicable only when “mcast” is set as “true” |
| type | The multicast transfer type. | string | Optional | Valid values: - “poly” - “rtp“ Applicable only when “mcast” is set as “true” |
| group | The Poly group being used. | integer | Optional | Valid values: numbers 1 through 25. Applicable only when: - “mcast” is set as “true” - “type” is set as “poly” |

**Sample Request: Play an audio file for 10 seconds, and multicast it to a Poly Group**

Custom

```json
POST https://10.12.123.12/api/controls/tone/start
{
  "duration": 10,
  "path": "chime.wav",
  "loop": true,
  "mcast": true,
  "playback": false,
  "state": {
    "mode": "sender",
    "address": "101.102.123.12",
    "port": "5000",
    "type": "poly",
    "group": 1
  }
}
```

JSON

**Sample Response**

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

#### 

#### Stop looping tone on firmware 5.5 and later

Stop the looping tone.

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

**URI**

`POST /api/controls/tone/stop`

**Parameters**

No parameters required for firmware 5.5 and later.

> [!NOTE]
> Note
> 
> For firmware 5.4 or earlier, you must use the parameter `path` to specify the ongoing tone. For example:
> 
> ```json
> POST https://10.12.123.12/api/controls/tone/stop
> {
> 	"path": "chime.wav"
> }
> ```

**Sample Request**

```json
POST https://10.12.123.12/api/controls/tone/stop
```

**Sample Response**

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

#### 

#### Start listening to a direct audio stream

Open the path to an audio stream to listen to.

**Applicable Products**: All except 8450, 8211, 8212

**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**

```json
POST https://10.12.123.12/api/controls/rx/start
{
	"port": "5001"
}
```

#### Upload, Play, and Delete an Audio File API

This API supports the following combined actions:

1. Upload a WAV (recommended) or MP3 audio file.
2. Play or multicast the audio.
3. Delete the file after playback completes.

##### Notes About This API

- Playback latency varies depending on the target device’s status and the audio file size. When the device is idle, the typical latency is:
  - 15-second audio file: approximately 60 seconds
  - 60-second audio file: approximately 90 seconds
- The `POST /api/controls/tone/upload-play` API supports two upload methods. Each method uses a different request format and HMAC signature (if the standard authentication method is used).

| Upload Method | Description | Request Format | HMAC String | Required Headers |
| --- | --- | --- | --- | --- |
| Raw file | Upload the binary data of an audio file directly | --data-binary "@<file_name>" | [request_method]:[request_uri]:[content_md5]:[content_type]:[timestamp]:[nonce] | - Authorization - Content-Md5 - Content-Type - Date |
| Multipart (File + JSON) | Upload an audio file with optional playback and multicast settings | -F "tone=@<file_name>" -F "data={...}" | [request_method]:[request_uri]:[timestamp]:[nonce] | - Authorization - Date |

##### API Specifications

**Applicable Products**: All IP Speakers, Paging Adapters, IP Intercoms, IP Visual Alerters, IP Displays, IP Clocks, IP Buttons

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/controls/tone/upload-play`

**Multipart Payload**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| data | Multipart payload to specify the audio file playback and multicast settings. |  | Optional | The multipart `data` field is optional. However, when provided, you must specify the Content-Type as “application/json”. - For example: `-F "data={\"loop\":true};type=application/json"` |
| duration | How long the audio plays (in seconds). | Integer | Optional |  |
| interval | When the audio file loop plays (`loop` set to `true`), set the pause time (in seconds) between each playback. | Integer | Optional |  |
| loop | Set the audio file to loop. | Boolean | Optional | Valid values: - “true” - “false” |
| mcast | Configure the device as a multicast transmitter. | Boolean | Optional | Valid values: - “true” - “false” If multicast is turned on via `/mcast/update` at any time, this call will default to these settings. If multicast is only configured via the web interface, this call will default to the web interface settings. |
| playback | Whether the device plays the uploaded audio file locally. | String | Optional | Valid values: - “true” - “false” |
| state | The multicast parameters. | String | Optional |  |
| mode | The multicast mode of the device | String | Optional | Valid values: - “sender” Applicable only when “mcast” is set as “true” |
| address | The IP address of the multicast zone. | String | Optional | Applicable only when “mcast” is set as “true” |
| port | The port of the multicast zone. | String | Optional | Applicable only when “mcast” is set as “true” |
| type | The multicast transfer type. | String | Optional | Valid values: - “poly” - “rtp“ Applicable only when “mcast” is set as “true” |
| group | The Poly group being used. | Integer | Optional | Valid values: numbers 1 through 25. Applicable only when: - “mcast” is set as “true” - “type” is set as “poly” |
| tone | The audio file to play back or multicast. |  | Required | **Note**: - All uploaded files are converted to 16kHz single-channel (Mono). - When using MP3 files, the Content-Type must be set as “audio/mpeg” |
| file | The binary data of the audio file. |  | Required | File format: - WAV with 16kHz sample rate (recommended) - MP3 with 16kHz sample rate |

**Sample Request 1:** Upload a WAV audio file, play it, then delete it.

```bash
curl -X POST "http://10.11.12.123/api/controls/tone/upload-play" \
  -H "Authorization: hmac admin:<nonce>:<hex_digest>" \
  -H "Content-Md5: <hex_md5>" \
  -H "Content-Type: audio/wav" \
  -H "Date: <RFC1123_date>" \
  --data-binary "@alert-lockdown.wav"
```

**Sample Request 2:** Upload a WAV file to the device, continuously play the file locally for 60 seconds with a 2-second pause between playbacks, multicast the audio to a specified zone, and then delete the file after playback completes.

```bash
curl -X POST \
  -H "Authorization: hmac admin:<nonce>:<digest>" \
  -H "Date: <date>" \
  -F "tone=@alert-lockdown.wav;type=audio/wav" \
  -F 'data={"loop":true,"interval":2,"duration":60,"mcast":true,"playback":true,"state":{"mode":"sender","address":"20.21.22.234","port":"50000","type":"rtp"}};type=application/json' \
  http://10.11.12.123/api/controls/tone/upload-play
```

**Sample Request 3:** Upload an MP3 file, play locally, multicast to a specified zone, then delete it.

```bash
curl -X POST \
  -H "Authorization: hmac admin:<nonce>:<digest>" \
  -H "Date: <date>" \
  -F "tone=@alert-lockdown.mp3;type=audio/mpeg" \
  -F 'data={"loop":false,"mcast":true,"playback":true,"state":{"mode":"sender","address":"20.21.22.234","port":"50002","type":"rtp"}};type=application/json' \
  http://10.11.12.123/api/controls/tone/upload-play
```

**Example Response**

On success, the device plays the audio and (if configured) multicasts it.

#### Stop listening to a direct audio stream

Close the path to an audio stream to stop listening.

**Applicable Products**: All except 8450, 8211, 8212

**Minimum Firmware Version**: 5.3.4

**URI**

`POST /api/controls/rx/stop`

**Sample Request**

```json
POST https://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**: 8190, 8190S, 8410, 8420, 8186, 8188, 8189, 8196, 8197, 8198, 8199, 8063, 8180g2, 8301, 8305, 8312, 8211, 8212

**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 |  |  |
| dtmf | Enable to play DTMF tones during the call to allow interoperability with DTMF-controlled multi-zone legacy communication systems. | String | Optional | - This parameter is available in firmware version 5.7 and later. - Use a comma to insert a pause between DTMF tones. Each comma (`,`) represents a 500 ms delay. For example: - `"dtmf": "12"`: The device plays tone 1 followed immediately by tone 2 (no pause). - `"dtmf": "1,2"`: The device plays tone 1, waits 500 ms, then plays tone 2. - `"dtmf": "1,,2"`: The device plays DTMF tone 1, waits 1000 ms, then plays tone 2. - Maximum length: 15 characters. |  |

**Sample Request:** The device calls extension 123. After the call connects, it dials DTMF tone 1. The device plays *chime.wav* repeatedly for up to 60 seconds, with a 3-second interval between playbacks.

```json
POST https://10.12.123.12/api/controls/call/start
{
	"extension": "123",
	"dtmf": "1",
	"tone": "chime.wav",
	"interval": "3",
	"maxdur": "60"
}
```

#### **End a call to a phone extension**

End a call to a phone extension.

**Applicable Products**: All speakers, 8301, 8305, 8312, 8211, 8212

**Minimum Firmware Version**: 3.3

**URI**

`POST /api/controls/call/stop`

**Sample Request**

```json
POST https://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

**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**

```json
POST https://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, 8312, 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**

```json
GET https://10.12.123.12/api/info/input.relay.status
```

**Sample Response**

```json
{
    "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**

```json
GET https://10.12.123.12/api/info/input.relay1.status
```

**Sample Response**

```json
{
    "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**

```json
POST https://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**

```json
POST https://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**

```json
POST https://10.12.123.12/api/controls/relay/enable
```

**Enable the 8063 Output Relay Momentarily**

Enable the output relay on the 8063 for a specified duration.

**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**

```json
POST https://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**

```json
POST https://10.12.123.12/api/controls/relay/disable
```

### Screen Control

You can use API commands to control content displayed on the IP Display, such as displaying an image or turning on a strobe light.

#### **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** |
| --- | --- | --- | --- | --- |
| stopAfter | How long the image stays (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |
| type | The type of background to display | String | Required | Set as “image” |
| image1 | The file name of the image | String | Required |  |

**Sample Request**

Custom

```json

POST https://10.12.123.12/api/controls/screen/start
{
	"stopAfter": 10,
    "type": "image",
	"image1": "school.jpeg"
}
```

JSON

**Sample Response**

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

  

#### **Display a slide or slideshow on the device screen**

Display a pre-defined slide or slideshow 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** |
| --- | --- | --- | --- | --- |
| screenName | The name of the slide or slideshow. | String | Required | If both a slide and a slideshow have the specified name, the device will display the slide. |
| stopAfter | How long the slide or slideshow stays (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |

**Sample Request**

Custom

```json

POST https://10.12.123.12/api/controls/screen/start
{
"screenName":"Evacuation",
"stopAfter":5
}
```

JSON

**Sample Response**

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

  

#### **Display text along with 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** |
| --- | --- | --- | --- | --- |
| stopAfter | How long the scrolling text stays (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |
| type | Specifies the type of background to display. | String | Required | Set as “image” |
| image1 | Specifies the file name of the image. | String | Required |  |
| text1 | Specifies the text to be displayed on the device. | String | Required |  |
| textBg | Whether to display the text background rectangle | Boolean | Optional | Valid values include: - “true” - “false” Default= “false” |
| textBgColor | Specifies the fill color of the text background rectangle |  |  | Valid values: - SVG color name - HEX code |
| textColor | Specifies the color of the text. | String | Optional | Valid values: - SVG color name - HEX code For example, use either of the following to set the text color as black: Custom ```json "textColor": "black" "textColor": "#000000" ``` JSON For more information, see [HTML Color Names](https://www.w3schools.com/colors/colors_names.asp). Default= “black” |
| textFont | Specifies the font of the text. | String | Optional | Valid values include: - “acumin” - “bookman” - “din” - “inter” - “nixie” - “overpass” - “roboto” Default= “inter” |
| textPosition | Specifies where the text should be displayed on the screen. | String | Optional | Valid values include: - “top” - “middle” - “bottom” Default= “bottom” |
| textScroll | Specifies whether to scroll the text. | String | Optional | Valid values include: - “true” - “false” Default=”true” |
| textScrollSpeed | Specifies the speed at which the text scrolls. | String | Optional | Valid values include (in increasing speed): - “1” - “2” - “3” - “4” - “5” Default= “1” |
| textSize | Specifies the size of the text. | String | Optional | Valid string values include: - “tiny“ (equal to integer value 60) - “small” (equal to integer value 100) - “medium” (equal to integer value 200) - “large” (equal to integer value 300) Valid integer values: 50 - 300 Default=”large” (in v5.6 and earlier) |

**Sample Request**

Custom

```json

POST https://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"
}
```

JSON

**Sample Response**

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

#### 

#### **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** |
| --- | --- | --- | --- | --- |
| stopAfter | How long the clock stays (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |
| 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 | Specifies whether to display the second hand on the digital clock. | Boolean | Optional | Use if type=digitalClock Default= “false” |
| clockSecondsAnalog | Specifies whether to display the second hand on the analog clock. | Boolean | Optional | Use if type= analogClock Default= “true” |
| clockSize | Specifies the size of the clock. | String | Optional | Valid values: - x-small - small - medium - large - x-large (default) |
| clockPosition | Specifies the position of the clock. | String | Optional | Valid values: - top-left - top-center - top-right - left - center - right - bottom-left - bottom-center - bottom-right Default= “center” |
| clockBgColor | Specifies the background color of the clock. | String | Optional | Use if type=digitalClock Valid values: - SVG color name - HEX code |
| clockFgColor | Specifies the foreground color of the clock. | String | Optional | Use if type=digitalClock Valid values: - SVG color name - HEX code Default= “white” |
| date | Specifies whether to display the date. | Boolean | Optional | Valid values: - true - false |
| datePosition | Specifies the position of the date information. | String | Optional | Valid values: - top-left - top-center - top-right - left - center - right - bottom-left - bottom-center - bottom-right Default= “bottom-center” |
| dateSize | Specifies the text size of the date information. | Integer |  | Valid values: 50 - 300 (default: 140) |
| dateColor | Specifies the text color of the date information. |  |  | Valid values: - SVG color name - HEX code Default= “black” |
| analogBgColor | Specifies the background color of the clock. | String | Optional | Use if type=analogClock Valid values: - SVG color name - HEX code |
| analogFgColor | Specifies the foreground color of the clock. | String | Optional | Use if type=analogClock Valid values: - SVG color name - HEX code Default= “black” |
| analogSecondsColor | Specifies the color of the seconds hand on the analog clock. | String | Optional | Use if type=analogClock Valid values: - SVG color name - HEX code |
| clockFont | Specifies 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 | Specifies the file name of the background image to use behind the clock. | String | Optional |  |

**Sample Request for Digital Clock**

Custom

```json

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

JSON

**Sample Request for Analog Clock**

Custom

```json

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

JSON

**Sample Response**

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

#### 

#### **Display flashing images on the device screen**

Display two 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** |
| --- | --- | --- | --- | --- |
| stopAfter | How long the flashing image stays (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |
| 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 | Required |  |

**Sample Request**

Custom

```json

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

JSON

**Sample Response**

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

#### Display a slideshow on the device screen using slide names

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

**Applicable Products**: 8410, 8420

**Minimum Firmware Version**: 5.3.4

**URI**

`POST /api/controls/screen/start`

**Parameter**

| Element | Description | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| stopAfter | How long the slideshow stays (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |
| 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**

```json
POST https://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.

#### 

#### Display a slide on the device screen using slide templates

Create a slide using a template and display it on the screen.

**Applicable Products**: 8410, 8420

**Minimum Firmware Version**: 5.3.

Note: The complete list of templates is available in firmware version 5.7 and later.

**URI**

`POST /api/controls/screen/start`

**Parameter**

| Element | Description | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| type | Specifies the slide content type. | String | Required | Set as “template” |
| template | Specifies the slide template type. | String | Required | Valid values: - "school_time" - "school_date_time" - "hospital_scrolling_text" - "hospital_text" - "hospital_time" - "announcement" - "dont_forget" - "reminder" - "today_is" - "time_date_bg" - "time_date_bg2" - "dualclock1" - "dualclock1_nocorner" - "dualclock2" - "dualclock3" - "calendar_time_date" - "calendar_time_image" - "calendar_analog_clock" - "weather_current" - "weather_hourly" - "weather_weekly" These values correspond to the templates available in the device's web interface under **Display** → **Slides** → **Template**. |
| showWeather | Specifies whether to show the weather widget (if configured). | Boolean | Optional | Valid values: - “true” - “false” Default= “true” |
| stopAfter | Specifies how long the slide stays (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |
| strobeFlash | Specifies the flashing pattern of the strobe light. | Integer | Optional | Valid values: - 15: Turns the strobe light off. - 0: Turns the strobe light on continuously. - 2: Uses the **Strobe Fast** pattern. - 3: Uses the **Slow Sweep** pattern. - 4: Uses the **Fast Sweep** pattern. - 5: Uses the **Reverse Slow Sweep** pattern. - 6: Uses the **Reverse Fast Sweep** pattern. - 7: Uses the **Flash All** pattern. - 8: Uses the **Alternate Sides** pattern. - 9: Uses the **Scan Slow** pattern. - 10: Uses the **Scan Fast** pattern. - 11: Uses the **Inside Out** pattern. - 12: Uses the **Single Flash** pattern. - 13: Uses the **Double Flash** pattern. - 14: Uses the **Triple Flash** pattern. |
| strobeColor | Specifies the color to display on the strobe. | String | Required if “strobeFlash” is set to 0 - 14 | Valid values: - "red” - "blue” - “green” - “amber” |
| strobeColor2 | Specifies the alternate color displayed by the strobe. | String | Optional | Valid values: - "red” - "blue” Note: This value is not available on all firmware versions. - “green” - “amber” |
| strobeLedlvl | Specifies the brightness of the strobe light. | String | Required if “strobeFlash” is set to 0 - 14 | \| Valid values: - Low: 0 - Medium: 56 - High: 255 \| \| --- \| |
| Valid values: - Low: 0 - Medium: 56 - High: 255 |
| **Template-specific parameters: “template”="school_time" or "school_date_time"** |
| icon1 | Specifies the icon that displays in the top-left section of the slide header. | String | Optional | **Note**: Icons larger than 1200px x 130px will be scaled to fit. |
| icon2 | Specifies the icon that displays in the top-right section of the slide header. | String | Optional | **Note**: Icons larger than 400px x 130px will be scaled to fit. |
| clockFormat | Specifies how the time is displayed on the clock (12-hour or 24-hour format). | String | Optional | Valid values: - “12hr” - “24hr” |
| clockSeconds | Specifies whether to display the seconds on the clock. | Boolean | Optional | Valid values: - “true” - “false” |
| colorScheme | Specifies the overall color theme used for the slide. | String | Optional | Valid values: - “bluegrey” - “greyblue” |
| layout | Specifies whether the date information displays on the left or right of the screen. | Integer | Optional | This parameter is available only when “template”="school_date_time". Valid values: - 1: The date is displayed in a rectangle on the left side of the display. - 2": The date is displayed in a rectangle on the right side of the display. |
| **Template-specific parameters: “template”="hospital_scrolling_text" or "hospital_text"** |
| icon1 | Specifies the icon that displays in the top-left section of the slide header. | String | Optional | Note: Icons larger than 1200px x 130px will be scaled to fit. |
| text1 | Specifies the text that scrolls across the bottom of the screen. | String | Optional |  |
| scrollSpeed | Specifies how fast text scrolls. | String | Optional | This parameter is available only when “template”="hospital_scrolling_text". Valid values include (in increasing speed): - “1” - “2” - “3” - “4” - “5” Default= “1” |
| **Template-specific parameters: “template”="hospital_time"** |
| icon1 | Specifies the icon that displays in the top-left section of the slide header. | String | Optional |  |
| clockFormat | Set how the time is displayed on the clock (12-hour or 24-hour format). | String | Optional | Valid values: - “12hr” - “24hr” |
| clockSeconds | Specifies whether to display the seconds on the clock. | Boolean | Optional | Valid values: - “true” - “false” |
| **Template-specific parameters: “template”="announcement"** |
| text1 | Specifies the white static text that displays at the top of the screen. | String | Optional |  |
| text2 | Specifies the yellow static text that displays at the bottom of the screen. | String | Optional |  |
| **Template-specific parameters: “template”="dont_forget"** |
| text1 | Specifies the static black text that displays at the top of the text frame. | String | Optional |  |
| text2 | Specifies the static white text that displays in the center of the text frame on a red background. | String | Optional |  |
| text3 | Specifies the static black text that displays at the bottom of the text frame. | String | Optional |  |
| **Template-specific parameters: “template”="reminder"** |
| text1 | Specifies the static red text that displays at the top of the text frame. | String | Optional |  |
| text2 | Specifies the static red text that displays in the center of the text frame. | String | Optional |  |
| text3 | Specifies the static white text that displays at the bottom of the text frame, on a red background. | String | Optional |  |
| **Template-specific parameters: “template”="today_is"** |
| text1 | Specifies the static black text that displays on the screen. | String | Optional |  |
| image1 | Specifies the background image. | String | Optional |  |
| **Template-specific parameters: “template”="time_date_bg" or "time_date_bg2"** |
| image1 | Specifies the background image. | String | Optional |  |
| font | Specifies the font used for the text. | String | Optional | Valid values include: - “acumin” - “bookman” - “din” - “inter” - “nixie” - “overpass” - “roboto” |
| textColor | Specifies the color of the date information. | String | Optional | Valid values: - SVG color name - HEX code For example, use either of the following to set the text color as black: Custom ```json "textColor": "black" "textColor": "#000000" ``` JSON For more information, see [HTML Color Names](https://www.w3schools.com/colors/colors_names.asp). Default= “black” |
| clockFgColor | Specifies the color of the time information. | String | Optional |
| clockFormat | Set how the time is displayed on the clock (12-hour or 24-hour format). | String | Optional | Valid values: - “12hr” - “24hr” |
| clockFont | Specifies the font used for the time and date information. | String | Optional |  |
| clockSeconds | Enable or disable the display of seconds on the clock. | Boolean | Optional | Valid values: - “true” - “false” |
| **Template-specific parameters: “template”="dualclock1", "dualclock1_nocorner", "dualclock2", or "dualclock3"** |
| image1 | Specifies the background image. | String | Optional |  |
| icon1 | Specifies the icon that displays on the upper-right of the screen. | String | Optional |  |
| clockSeconds | Enable or disable the display of seconds on the digital clock. | Boolean | Optional | Valid values: - “true” - “false” |
| clockSecondsAnalog | Enable or disable the display of seconds on the analog clock. | Boolean | Optional | Valid values: - “true” - “false” |
| analogSecondsColor | Specifies the color of the clock second hand. | String | Optional | These parameters are available only when “template”="dualclock1", or or "dualclock3" “dualclock1_nocorner” Valid values: - SVG color name - HEX code For example, use either of the following to set the text color as black: Custom ```json "dualClock1Color": "black" "dualClock1Color": "#000000" ``` JSON For more information, see [HTML Color Names](https://www.w3schools.com/colors/colors_names.asp). Default= “black” |
| dualClock1Color | Specifies the color of the clock and graphical elements. | String | Optional |
| **Template-specific parameters: “template”="calendar_time_date", "calendar_analog_clock", or "calendar_time_image"** |
| icon1 | Specifies the icon that displays on the lower-left of the screen. | String | Optional |  |
| colorScheme | Sets the overall color theme used for the slide. | String | Optional | Valid values: - “light” - “dark” |
| image1 | Specifies the background image. | String | Optional | This parameter is available only when “template”="calendar_time_image". |
| **Template-specific parameters: “template”="weather_current", "weather_hourly", or "weather_weekly"** |
| clockFormat | Set how the time is displayed on the clock (12-hour or 24-hour format). | String | Optional | Valid values: - “12hr” - “24hr” |
| clockSeconds | Enable or disable the display of seconds on the digital clock. | Boolean | Optional | Valid values: - “true” - “false” |
| headline | Specifies whether to show a headline. | String | Optional | Valid values: - "date": This shows the date as the headline. - "location": This shows the location as the headline (only available for Canada weather). - "none": Do not show a headline. |
| showExtra | Specifies whether to show “Feels Like” data. | String | Optional | Valid values: - "1": This shows "Feels Like" data. - "0": Do not show "Feels Like" data |

**Sample Request:** Display a slide created using the template, with a strobe light on, and display the slide for 10 seconds

```json
POST https://10.12.123.12/api/controls/screen/start
{
"type": "template",
"template": "hospital_time",
"stopAfter": 10,
"strobeFlash": 2,
"strobeColor": "amber",
"strobeLedlvl": 255
}
```

**Sample Response**

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

#### Stop a screen pattern and return the screen to default

Return a screen to its default setting.

**Applicable Products**: 8410, 8420

**Minimum Firmware Version**: 5.3.4

**URI**

`POST /api/controls/screen/stop`

**Sample Request**

```json
POST https://10.12.123.12/api/controls/screen/stop
```

**Sample Response**

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

#### **Display text over the existing device screen**

Display text on the device screen. If a slide, slideshow, or image display is ongoing, the text is added on top of the content.

**Applicable Products**: 8410, 8420

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/controls/screen-text/start`

**Parameter**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| duration | How long the text displays (in seconds). | Integer | Optional | If not specified, the text displays indefinitely. |
| persistent | Whether the text continues to display when the screen content changes. | Boolean | Optional | Valid values include: - “true” - “false” Default=”false” |
| textContent | The text to be displayed on the device. | String | Required |  |
| textBg | The text background. | Boolean | Optional | Valid values: - “true” - “false” |
| textBgColor | The text background color. | String | Optional | Valid values: - SVG color name - HEX code |
| textColor | The color of the text. | String | Optional | Valid values: - SVG color name - HEX code For example, use either of the following to set the text color to black: ```bash "textColor": "black" "textColor": "#000000" ``` For more information, see [HTML Color Names](https://www.w3schools.com/colors/colors_names.asp). 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 | Whether text scroll is enabled. | Boolean | Optional | Valid values include: - “true” - “false” Default=”true” |
| textScrollSpeed | The speed at which the text scrolls. | String | Optional | Valid values include (in increasing speed) - “1” - “2” - “3” - “4” - “5” Default= “1” |
| textSize | The size of the text. | String or Integer | Optional | Valid string values include: - “tiny“ (equal to integer value 60) - “small” (equal to integer value 100) - “medium (equal to integer value 200) - “large” (equal to integer value 30) Valid integer values: 50 - 300 Default=”large” (in v5.6 and earlier) Default=”small” (in v5.7 and later) |

**Sample Request**

```bash
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: hmac <user>:<nonce>:<digest>" \
    -d '{
        "textContent": "Emergency Notice: Stand by for instructions",
        "textColor": "#FFFFFF",
        "textFont": "Roboto",
        "textSize": "large",
        "textPosition": "bottom",
        "textScroll": true,
        "textScrollSpeed": 3,
        "textBg": true,
        "textBgColor": "#000000",
        "duration": 10
    }' \
    https://10.12.123.12/api/controls/screen-text/start
```

**Sample Response**

None. The observable outcome is whether the text is displayed on the screen.

#### **Stop displaying text over the existing device screen**

Stop the text displaying on the device screen.

**Applicable Products**: 8410, 8420

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/controls/screen-text/stop`

**Sample Request**

```bash
curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: hmac <user>:<nonce>:<digest>" \    
    https://10.12.123.12/api/controls/screen-text/stop
```

**Sample Response**

None. The observable outcome is whether the text display stops.

#### Turn on the strobe light

You can use the parameters below to enable a strobe light on the 8410/8420. These parameters work with the following commands:

- [Display a single image on the device screen](/v1/docs/restful-api-guide#display-a-single-image-on-the-device-screen)
- [Display scrolling text over an image on the device screen](/v1/docs/restful-api-guide#display-scrolling-text-over-an-image-on-the-device-screen)
- [Display a clock on the device screen](/v1/docs/restful-api-guide#display-a-clock-on-the-device-screen)
- [Display flashing images on the device screen](/v1/docs/restful-api-guide#display-flashing-images-on-the-device-screen)
- [Display a slide on the device screen using slide templates](/v1/docs/restful-api-guide#display-a-slideshow-on-the-device-screen-using-slide-names)
- [Display a slideshow on the device screen using slide names](/v1/docs/restful-api-guide#display-a-slideshow-on-the-device-screen-using-slide-names)
- [Display text over the existing device screen](/v1/docs/restful-api-guide#display-scrolling-text-over-an-image-on-the-device-screen)

| Element | Description | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| strobeFlash | The strobe flash pattern to use | Integer | Required | Valid values: See [Algo Strobe Light Pattern Reference Guide](https://docs.algosolutions.com/docs/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: - Low: 0 - Medium: 56 - High: 255 |

**Related Links**

- [Algo Strobe Light Pattern Reference Guide](https://docs.algosolutions.com/docs/algo-strobe-light-pattern-reference-guide)

####

### 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, 8410, 8420

**Minimum Firmware Version**: 3.3

**URI**

`POST /api/controls/strobe/start`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| duration | How long the strobe light is on (in seconds). | Integer | Optional | This parameter is available only on firmware v5.7 and later. |
| pattern | The number of the pattern set. | Integer | Required | Valid values: See [Algo Strobe Light Pattern Reference Guide](https://docs.algosolutions.com/docs/algo-strobe-light-pattern-reference-guide) |
| color1 | The color to set the strobe | String | Required | Valid values: - "red” - "blue” - “green” - “amber” |
| color2 | The second color for the strobe to use if the pattern uses two colors. | String | Optional | Only applicable to 8138/8410/8420. Valid values: - "red” - "blue” - “green” - “amber” |
| ledlvl | The brightness of the strobe light. | String | Required | For 8190S: - Low: 1 - Medium: 2 - High: 3 For 8128(G2)/8138/8410/8420: - Low: 0 - Medium: 56 - High: 255 |

**Related Links**

- [Algo Strobe Light Pattern Reference Guide](https://docs.algosolutions.com/docs/algo-strobe-light-pattern-reference-guide)

**Sample Request**

Custom

```json
POST https://10.12.123.12/api/controls/strobe/start
{
	"duration": 10,
    "pattern": 1,
	"color1": "red",
	"color2": "blue",
	"ledlvl": 100
}
```

JSON

**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, 8410, 8420

**Minimum Firmware Version**: 3.3

**URI**

`POST /api/controls/strobe/stop`

**Sample Request**

```json
POST https://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 an 8450 Button

Activate a button on an 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 **Identifier** you configured for the button on its configuration screen. **To find your button ID:** 1. Log in to your 8450 device web interface. 2. Go to **Screens**. Then select the screen where your button is located. 3. Find the button and copy its **Identifier.** ![](https://cdn.document360.io/f6f5e62d-d280-487f-9da7-5926ffd53b5f/Images/Documentation/New Project (29).png) |

**Sample Request**

```json
POST https://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.

> [!NOTE]
> 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 active non-emergency paging. - “call” : Stop an active SIP call. - “pageMic” : Stop live paging through 8450 microphone. - “pageTone” : Stop ongoing tones or pre-recorded announcements. |

**Sample Request**

```json
POST https://10.12.123.12/api/controls/console/event/stop
{
"type":"all"
}
```

**Sample Response:**

```json
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`

**Sample Request**

```json
GET https://10.12.123.12/api/console/event/status
```

**Sample Response:**

```json
{"active":[ 

               {"type":"emergency"}, 

               {"type":"pageMic"} 

]}
```

### Emergency Alerts

You can use API commands to start or stop an emergency alert.

#### Start an Emergency Alert

Start an emergency alert.

**Applicable Products**: All IP Speakers, Paging Adapters, IP Visual Alerters, IP Displays

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/controls/emergency-alert/start`

**Payload**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| announcement | The ID number of the emergency alert. In the device web interface, this corresponds to the **Announcement** number under **Additional Features → Emergency Alerts**. For example, for **Announcement 2**, the ID is `2`. | integer | Required | Valid values: 1-10 |

**Sample Request 1:** Start emergency 1.

```bash
curl -X POST \
  -H "Authorization: hmac <user>:<nonce>:<digest>" \
  -H "Content-Md5: <hex_md5>" \
  -H "Content-Type: application/json" \
  -H "Date: <RFC1123_date>" \
  -d '{"announcement":"1"}' \
  http://10.11.12.123/api/controls/emergency-alert/start
```

**Example Response**

On success, the device plays the emergency alert.

#### Stop an Emergency Alert

Stop an ongoing emergency alert.

**Applicable Products**: All IP Speakers, Paging Adapters, IP Visual Alerters, IP Displays, IP Buttons

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/controls/emergency-alert/stop`

**Sample Request 1:** Stop the ongoing emergency.

```bash
curl -X POST \
  -H "Authorization: hmac <user>:<nonce>:<digest>" \
  -H "Content-Md5: <hex_md5>" \
  -H "Content-Type: application/json" \
  -H "Date: <RFC1123_date>" \ 
  http://10.11.12.123/api/controls/emergency-alert/stop
```

**Example Response**

On success, the device stops the emergency alert.

### Scheduler

You can use API commands to query, create, delete, update, skip, or restore events and groups.

You can also apply tags to identify events and batch-process them later.

> [!NOTE]
> Note
> 
> - You can combine multiple API requests into a single command. For example, you can create one event and delete another in the same request.
> - If any operation in a request fails, the entire transaction is rolled back and no changes are committed.
> - Use HTTPS with the **Standard** or **Basic** authentication method.

#### Prerequisites

All examples in this section use the **Standard** authentication method, which requires:

- Setting **Authentication Method** to **Standard** (under **Advanced Settings** → **Admin**).
- Setting a **RESTful API Password** (under **Advanced Settings** → **Admin**).
- Ensuring your computer’s time zone matches the device’s time zone.

The HMAC timestamp validation required by **Standard** API authentication must fall within the timestamp tolerance, which is controlled by `api.auth.tsvar` (30 seconds by default).

> [!NOTE]
> **Note**
> 
> If you want to use the **Basic** authentication in API calls, include an authentication payload by encoding the RESTFUL API username (admin) and password in Base64.

#### Retrieve All Schedules

Retrieve the full Scheduler database, including events, groups, and events inside each group.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`GET /api/schedules`

**Parameters**

None.

**Sample Request Format**

```json
curl -X GET \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        https://10.12.123.12/api/schedules
```

**Response Format**

```json
{
  "format": "v2.0",
  "groups": [
    <Group>
  ],
  "events": [
    <Event>
  ]
}
```

**Example Response**

```json
{
  "format": "v2.0",
  "events": [
    {
      "enabled": 1,
      "api_call": [],
      "greyed_out_date": "",
      "tag": "",
      "start_time": "12:00",
      "duration": "",
      "exdate": "",
      "evid": 1,
      "extension": "",
      "mgroup": "NULL",
      "audio": "bell-na.wav",
      "event_type": "play_tone",
      "dtmf": "2",
      "name": "Lunch Break",
      "auto_remove": 0,
      "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR",
      "start_date": "2026-09-01",
      "color": "#ff8800",
      "zone": 1,
      "rdate": ""
    }
  ],
  "groups": [
    {
      "color": "#dd036d",
      "rdate": "",
      "groupid": 1,
      "start_date": "2026-02-25",
      "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR",
      "name": "School Day",
      "events": [
        {
          "enabled": 1,
          "api_call": [],
          "greyed_out_date": "",
          "tag": "",
          "start_time": "08:00:00",
          "duration": "",
          "exdate": "",
          "evid": 2,
          "extension": "",
          "audio": "bell-na.wav",
          "event_type": "play_tone",
          "rdate": "",
          "name": "Morning Bell",
          "auto_remove": 0,
          "rrule": "",
          "start_date": "",
          "color": "#dd036d",
          "zone": 1,
          "dtmf": ""
        }
      ]
    }
  ]
}
```

#### Retrieve Scheduled Event Instances Within a Date Range[****](https://trac.algosolutions.com/docs/shared/libaphp/docs/Scheduler%20v2%20-%20REST%20API.html#retrieve-scheduled-events-instances-within-a-date-range)

Retrieve scheduled event instances within a specified date range.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`GET /api/schedules?events=&lt;date&gt;&amp;days=&lt;number&gt;`

**Parameters**

| **Element** | Description | Format / Type | Required | Note |
| --- | --- | --- | --- | --- |
| `events` | Start date. | String (YYYY-MM-DD) | Required |  |
| `days` | Number of days to return. | Integer | Required | Default value: 1 |

**Sample Request:** Query 7-day schedules starting from today

```plaintext
curl -X GET `
        -H "Authorization: hmac <user>:<nonce>:<digest>" `
        https://10.12.123.12/api/schedules?events=&days=7
```

**Sample Request:** Query 7-day schedules starting from a specified date

```plaintext
curl -X GET \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        https://10.12.123.12/api/schedules?events=2026-02-15&days=7
```

**Example Response:**

```json
{
  "format": "v2.0",
  "events": {
    "2026-02-15": [],
    "2026-02-16": [],
    "2026-02-17": [],
    "2026-02-18": [],
    "2026-02-19": [
      {
        "evid": 9,
        "color": "#88fc0b",
        "name": "Emergency Alert",
        "start_time": "13:13:00",
        "skipped": 0
      }
    ],
    "2026-02-20": [
      {
        "evid": 9,
        "color": "#88fc0b",
        "name": "Emergency Alert",
        "start_time": "13:13:00",
        "skipped": 0
      }
    ],
    "2026-02-21": [
      {
        "evid": 9,
        "color": "#88fc0b",
        "name": "Emergency Alert",
        "start_time": "13:13:00",
        "skipped": 0
      }
    ]
  }
}
```

#### **Create Stand-Alone Events**[****](https://trac.algosolutions.com/docs/shared/libaphp/docs/Scheduler%20v2%20-%20REST%20API.html#create-stand-alone-events)

Create standalone events.

> [!NOTE]
> Note
> 
> Don’t specify`evid` when creating new events. Otherwise, if an event with the specified `evid` already exists, the existing event is updated instead, regardless where is its location.

The event type is decided by `event_type` :

- `play_tone` : Creates a **Play Tone** event. An event ID `evid` is automatically created.
- `stream_audio` : Creates a **Stream Audi**o event. An event ID `evid` is automatically created.
- `sip_call` : Creates a **SIP Call with Tone** event. An event ID `evid` is automatically created.
- `api_call` : Creates an **API Call** event. An event ID `evid` and API Call IDs`actid`are automatically created. You can add up to 5 API calls in one API Call event.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

Refer to the following links for the event structure and parameters required by each event type:

- [Event Structure: Play Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-play-tone)
- [Event Structure: Stream Audio](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-stream-audio)
- [Event Structure: SIP Call with Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-sip-call-with-tone)
- [Event Structure: API Call](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-api-call)

**Sample Request:** Create a standalone **Play Tone** event

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
        "events": [
        {
        "event_type": "play_tone",
        "name": "Lunch Bell",
        "start_time": "12:00",
        "zone": 1,
        "audio": "bell-na.wav",
        "start_date": "2026-09-01",
        "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
        "rdate": "",
        "exdate": "",
        "color": "#ff8800"
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
```

**Sample Response**

```json
{
  "rdate": "",
  "duration": "",
  "greyed_out_date": "",
  "evid": 13,
  "exdate": "",
  "auto_remove": 0,
  "extension": "",
  "start_date": "2026-09-01",
  "start_time": "12:00",
  "zone": 1,
  "color": "#ff8800",
  "enabled": 1,
  "tag": "",
  "api_call": [],
  "name": "test",
  "audio": "bell-na.wav",
  "event_type": "play_tone",
  "dtmf": "",
  "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR"
}
```

#### **Update Events**

Update specified events. The target events are identified by the provided `evid`.

> [!NOTE]
> Note
> 
> - If no `evid` or `actid` are provided, or if the IDs are invalid, new events are created based on the specified `event_type`.
> - Include only the parameters you want to modify. All other parameters remain unchanged.
> - To update an **API Call** event, provide at least two IDs:
>   - `evid`: The ID of its host event.
>   - `actid`: The ID for the API calls.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| `events` | Create or update events | Array of events | Required | You must specify a valid `evid`. |

**Sample Request**: Update an API Call event payload

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
        "events": [
        {
        "evid": 1,
        "api_call": [
        {
        "actid": 1,
        "payload": "{\"path\":\"chime.wav\",\"loop\":false}"
        }
        ]
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
```

**Sample Response**

```json
{
  "events": [
    {
      "evid": 1,
      "api_call": [
        {
          "actid": 1,
          "payload": "{\"path\":\"chime.wav\",\"loop\":false}"
        }
      ]
    }
  ]
}
```

#### **Create a Group**[****](https://trac.algosolutions.com/docs/shared/libaphp/docs/Scheduler%20v2%20-%20REST%20API.html#create-group-of-events)

Create a group of events.

> [!NOTE]
> Note
> 
> - Don’t specify `groupid` when creating a new group. Otherwise, if a group with the specified `groupid` already exists, the existing group is updated instead.
> - Don’t specify`evid` when adding new events to the group. Otherwise, if an event with the specified`evid` already exists, the existing event is updated instead, regardless where is its location.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| `groups` | Create groups with nested events | Array of groups | Required |  |

To add events to a group, refer to the following links for the event structure and parameters required by each event type:

- [Event Structure: Play Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-play-tone)
- [Event Structure: Stream Audio](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-stream-audio)
- [Event Structure: SIP Call with Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-sip-call-with-tone)
- [Event Structure: API Call](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-api-call)

**Request Format**

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
        "groups": [
        {
        ...
        "events": [
        {
        "event_type": "play_tone",
        ...
        },
        {
        "event_type": "sip_call",
        ...
        }
        ]
        }
        ]
        }' \
        "https://10.12.123.12/api/schedules"
```

**Sample Body Request**

```json
{
  "groups": [
    {
      "name": "Morning Music",
      "color": "#3366ff",
      "start_date": "2026-02-21",
      "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
      "rdate": "",
      "events": [
        {
          "event_type": "play_tone",
          "name": "Start of Day",
          "enabled": true,
          "start_time": "08:30",
          "duration": 30,
          "zone": 1,
          "audio": "bell-na.wav",
          "color": "#33cc99"
        },
        {
          "event_type": "api_call",
          "name": "Notify PA",
          "enabled": true,
          "start_time": "08:50",
          "color": "#33cc99",
          "api_call": [
            {
              "method": "POST",
              "target": "https://10.0.0.10",
              "path": "/api/controls/tone/start",
              "header": "Content-Type: application/json",
              "payload": "{\"path\":\"chime.wav\",\"loop\":false,\"mcast\":false}"
            }
          ]
        }
      ]
    }
  ]
}
```

**Sample Response**

```json
{
  "groups": [
    {
      "name": "Morning Music",
      "groupid": 1,
      "rrule": "FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR",
      "events": [
        {
          "audio": "bell-na.wav",
          "duration": 30,
          "start_time": "08:30",
          "name": "Start of Day",
          "evid": 2,
          "event_type": "play_tone",
          "enabled": true,
          "color": "#33cc99",
          "zone": 1
        },
        {
          "enabled": true,
          "evid": 3,
          "api_call": [
            {
              "actid": 2,
              "method": "POST",
              "payload": "{\"path\":\"chime.wav\",\"loop\":false,\"mcast\":false}",
              "header": "Content-Type: application/json",
              "target": "https://10.0.0.10",
              "path": "/api/controls/tone/start"
            }
          ],
          "event_type": "api_call",
          "start_time": "08:50",
          "color": "#33cc99",
          "name": "Notify PA"
        }
      ],
      "rdate": "",
      "start_date": "2026-02-21",
      "color": "#3366ff"
    }
  ]
}
```

#### **Update Groups**

Update an existing group or its nested events. The target groups and events are identified by the provided `groupid` and event IDs (`evid` or `actid`).

> [!NOTE]
> Note
> 
> - If no IDs are provided, or if the IDs are invalid, new group or event instances are created.
> - Include only the parameters you want to modify. All other parameters remain unchanged.
> - To update an **API Call** event in a group, provide at least these IDs:
>   - `groupid`: The ID of the host group.
>   - `evid`: The ID of its host event.
>   - `actid`: The ID for the API calls.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| `groups` | Create groups with nested events. | Array of groups. | Required | You must specify a valid `groupid`. |

**Sample Request:** Update a group by `groupid`

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d
        '{
        "groups": [
        {
        "groupid": 1,
        "rrule": "FREQ=WEEKLY;BYDAY=MO,FR"
        }
        ],
        "events": [
        {
        "name": "Open Day",
        "evid": 2
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
```

#### [****](https://trac.algosolutions.com/docs/shared/libaphp/docs/Scheduler%20v2%20-%20REST%20API.html#update-groups)

**Sample Response**

```json
{
  "events": [
    {
      "evid": 2,
      "name": "Open Day"
    }
  ],
  "groups": [
    {
      "rrule": "FREQ=WEEKLY;BYDAY=MO,FR",
      "groupid": 1
    }
  ]
}
```

#### **Delete Events or Groups**

Delete events or groups by specifying their IDs.

> [!NOTE]
> Note
> 
> When you delete a group, all events it contains are also deleted.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | Description | Format / Type | Required | Note |
| --- | --- | --- | --- | --- |
| `delete` | Delete events or groups. | Array of objects. | Required | Specify the target event or group IDs: - `evid`: Event ID for **Play Tone**, **Stream Audio**, or **SIP Call with Tone.** - `actid`: **API Call** event ID. - `groupid`: Group ID. |

**Sample Request:** Delete a group and an API Call event

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '
        {
        "delete": [
        {
        "groupid": 1
        },
        {
        "actid": 3
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
```

**Sample Response**

```json
{
  "delete": [
    {
      "groupid": 1
    },
    {
      "actid": 3
    }
  ]
}
```

[****](https://trac.algosolutions.com/docs/shared/libaphp/docs/Scheduler%20v2%20-%20REST%20API.html#delete-stand-alone-events)

#### Exclude Event or Group Instances from a Specified Date

Remove instances of the specified event or group on a specified date.

Excluded events or group instances do not appear in the **Calendar**, but they can be restored if needed.

> [!NOTE]
> Note
> 
> - This command does not modify the event definition itself.
> - Use `evid: -1` to target all events (including both standalone events and events inside groups) that have an occurrence on the specified date.
> 
> When using `evid: -1`, the response includes `affected_events` which lists all available events.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| `exclude` | Remove event instances on a specified date. | Array of objects. | Required | - Use `exdate` ( `YYYY-MM-DD`) to specify the date. - Use `evid`to specify events. - Use `groupid`to specify groups. |

**Sample Request**: Exclude event instances on a specified date

```plaintext
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{"exclude":[{"evid":4,"exdate":"2026-09-01"}]}' \
        https://10.12.123.12/api/schedules
```

**Sample Response**

```json
{
  "exclude": [
    {
      "evid": 4,
      "exdate": "2026-09-01"
    }
  ]
}
```

#### **Restore Excluded Event or Group Instances**[****](https://trac.algosolutions.com/docs/shared/libaphp/docs/Scheduler%20v2%20-%20REST%20API.html#re-add-a-deleted-event-s-instance)

Restore excluded event or group instances on a specified date.

> [!NOTE]
> Note
> 
> - This command does not modify the event or group definition itself.
> - Use `evid: -1` to target all events (including both standalone events and events inside groups) that have an occurrence on the specified date.
> 
> When using `evid: -1`, the response includes `affected_events` which lists all available events.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| `remove_exclude` | Restore event or group instances on a specified date. | Array of objects. | Required | - Use `date` ( `YYYY-MM-DD`) to specify the date. - Use `evid`to specify events. - Use `groupid`to specify groups. |

**Sample Request:** Restore event instances on a specified date

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
        "remove_exclude": [
        {
        "evid": 4,
        "date": "2026-09-01"
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
```

**Sample Response**

```json
{
  "remove_exclude": [
    {
      "date": "2026-09-01",
      "evid": 4
    }
  ]
}
    
```

#### Skip Event or Group Instances

Remove event or group instances from a specified date.

Skipped events or groups still appear in the **Calendar** and can be restored if needed.

> [!NOTE]
> Note
> 
> - This command does not modify the event definition itself.
> - Use `evid: -1` to target all events (including both standalone events and events inside groups) that have an occurrence on the specified date.
> 
> When using `evid: -1`, the response includes `affected_events` which lists all available events.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| `skip` | Skip event or group instances on a specified date. | Array of objects. | Required | - Use `date` ( `YYYY-MM-DD`) to specify the date. - Use `evid`to specify standalone events. - Use `groupid`to specify groups. |

**Sample Request:** Skip a group instance from a specified date

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{"skip":[{"groupid":101,"date":"2025-12-01"}]}' \
        https://10.12.123.12/api/schedules
```

**Sample Response**

```json
{
  "skip": [
    {
      "groupid": 101,
      "date": "2025-12-01"
    }
  ]
}
    
```

#### **Restore Skipped Event or Group Instances**

Restore skipped event or group instances.

> [!NOTE]
> Note
> 
> - This command does not modify the event or group definition itself.
> - Use `evid: -1` to target all events (including both standalone events and events inside groups) that have an occurrence on the specified date.
> 
> When using `evid: -1`, the response includes `affected_events` which lists all available events.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Notes** |
| --- | --- | --- | --- | --- |
| `remove_skip` | Restore event or group instances on a specified date. | Array of objects | Required | - Use `date` ( `YYYY-MM-DD`) to specify the date. - Use `evid`to specify events. - Use `groupid`to specify groups. |

**Sample Request:** Restore all skipped events for the specified day

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
        "remove_skip": [
        {
        "evid": -1,
        "date": "2026-03-09"
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
    
```

**Sample Response**

> [!NOTE]
> Note
> 
> The response returns all events for the day with its latest state (regardless of whether they were skipped before the change).

```json
{
  "remove_skip": [
    {
      "evid": -1,
      "date": "2026-03-09",
      "affected_events": [
        {
          "start_time": "00:00:00",
          "name": "Start a strobe",
          "evid": 1,
          "recurrent": 1,
          "skipped": 0,
          "color": "#cdebfa"
        },
        {
          "skipped": 0,
          "group": "Morning Music",
          "group_color": "#3366ff",
          "color": "#33cc99",
          "name": "Open Day",
          "recurrent": 1,
          "groupid": 1,
          "start_time": "08:30",
          "evid": 2
        },
        {
          "skipped": 0,
          "group": "Morning Music",
          "group_color": "#3366ff",
          "color": "#33cc99",
          "name": "Notify PA",
          "recurrent": 1,
          "groupid": 1,
          "start_time": "08:50",
          "evid": 3
        }
      ]
    }
  ]
}
```

#### Apply Tags to Events

You can use tags to identify events and batch manage them later.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** |
| --- | --- | --- | --- |
| `events` | Action to perform. | Array of objects | Required |
| `tag` | Event tag. | String | Required |

**Sample Request**: Add the tag “Test” to an existing event

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
        "events": [
        {
        "evid": 1,
        "tag": "Test"
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
    
```

**Sample Response**

```json
{
  "events": [
    {
      "evid": 1,
      "tag": "Test"
    }
  ]
}
```

#### Delay the Start of an Event

You can use `delay` to postpone the triggering of events after its creation time.

> [!NOTE]
> Note
> 
> If you specify `delay`, don’t set the `start_date` and `start_time`. Otherwise, the schedule fails.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** | **Note** |
| --- | --- | --- | --- | --- |
| `events` | Action to perform. | Array of objects | Required |  |
| `delay` | Postpone the event triggering time in seconds. | Integer | Required | To ensure the event is entered into the Scheduler in time to be activated, set the delay time to at least 10 seconds. |

**Sample Request**: Trigger an event one minute after its creation

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
         "events": [
        {
          "name": "DELAYED TIMER",
          "color": "#ffcc99",
          "event_type": "play_tone",
          "audio": "bell-na.wav",
          "delay": "20",
          "auto_remove": 1
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
    
```

**Sample Response**

```json
{
  "events": [
    {
      "start_date": "2026-02-03",
      "audio": "bell-na.wav",
      "name": "DELAYED TIMER",
      "event_type": "play_tone",
      "delay": "20",
      "color": "#ffcc99",
      "auto_remove": 1,
      "start_time": "10:29:09",
      "evid": 12
    }
  ]
}
```

#### Batch Manage Events Using Tags

You can use tags to batch manage events, including:

- `delete` : Delete events.
- `exclude` : Exclude a date.
- `remove_exclude` : Re-add the excluded date.
- `skip` : Skip events.
- `remove_skip` : Restore skipped events.

**Applicable Products**: 8301, 8305, 8312

**Minimum Firmware Version**: 5.7

**URI**

`POST /api/schedules`

**Parameters**

| **Element** | **Description** | **Type** | **Required** |
| --- | --- | --- | --- |
| - `delete` - `exclude` - `remove_exclude` - `skip` - `remove_skip` | Action to perform. | Array of objects | Required |
| `tag` | Event tag. | String | Required |

**Sample Request**: Skip all events tagged as “Test” on a specified date

```json
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Authorization: hmac <user>:<nonce>:<digest>" \
        -d '{
        "skip": [
        {
        "tag":"Test",
        "date": "2026-12-01"
        }
        ]
        }' \
        https://10.12.123.12/api/schedules
    
```

**Sample Response**

```json
{
  "skip": [
    {
      "date": "2026-12-01",
      "tag": "Test"
    }
  ]
}
```

#### Event Structure

Refer to the following section for the structure and available parameters for different event types.

##### Event Structure: Play Tone

This table shows parameters available to the event type **Play Tone**.

| **Element** | **Description** | **Type** | **Required** | **Note** |
| --- | --- | --- | --- | --- |
| `api_call` | Specifies the API call(s) to execute. | String | N/A | If an event includes `api_call` entries but its `event_type` is not `api_call`, the associated `api_call` entries are ignored. |
| `audio` | The audio file to play. | String | Required | Valid values: - Any audio file name that is available in **System** → **File Manager**. |
| `auto_remove` | Deletes all instances of the event or group after it is triggered. | Boolean or `0/1` | Optional | Default value: 0. This can be used to remove temporary schedules intended for testing purposes. |
| `color` | The color of the event to display on the **Calendar**. | String (Hex color value) | Required | If not specified, a unique color is assigned automatically for each new event. |
| `delay` | Postpone the event triggering time in seconds. | Integer | Optional | if specified, the event starts after the specified `delay` period, calculated from the event creation time. - If specified, don’t specify the `start_date` or `start_time`. Otherwise, the schedule fails. - To ensure the event is entered into the Scheduler in time to be activated, set the delay time to at least 10 seconds. |
| `dtmf` | The DTMF tone to play before the tone. | Integer | Optional | Used only when the following configuration is set: **Advanced Settings** → **Advanced Audio** → **Play DTMF Tones Before Pages/Alerts** and set **Alert Specific** for **DTMF Tone(s)**. |
| `duration` | The duration of this event in seconds. | Integer | N/A | Don’t specify. It’s generated automatically. |
| `enabled` | Whether this event is enabled. | Boolean or `0/1` | Optional | Default value: 1 |
| `event_type` | The event type. | Enum | Required | Valid values: - `play_tone` |
| `evid` | The unique ID of the event. | Integer | Optional | Leave it empty to create a new event. Specify the ID to update an existing event. |
| `exdate` | Specifies dates to exclude from the recurrence set generated by `rrule` and `rdate`. | String (YYYY-MM-DD) | Optional |  |
| `extension` | The target SIP extension. | Integer | N/A |  |
| `greyed_out_date` | Days that have skipped events or groups. | String (YYYY-MM-DD) | N/A | Don’t specify. It’s generated automatically. |
| `mgroup` | Poly page group ID. | Integer | N/A | Specify the target Poly page group ID when you have set Multicast Type to one of the following in **Basic Settings** → **Multicast**: - Poly Group Page - Poly Push-to-Talk - Regular RTP + Poly Group Page - Regular RTP + Poly Push-to-Talk |
| `name` | The name of the event. | String | Required |  |
| `rdate` | Specifies additional custom dates on which the event occurs, beyond those defined by `rrule`. | String (YYYY-MM-DD) | N/A |  |
| `rrule` | Defines the recurrence pattern of a repeating event, including the frequency and optional rule components such as `INTERVAL`, `COUNT`, `UNTIL`, and `BYDAY`. | String | Required | Must include `FREQ=`. Valid `FREQ `values: - `DAILY` - `WEEKLY` - `MONTHLY` - `YEARLY` No whitespace allowed. |
| `start_date` | The start date of the event. | String (YYYY-MM-DD) | Required |  |
| `start_time` | The start time of the event. | String (HH-MM:SS) | Required |  |
| `tag` | An optional identifier for events. This identifier can be used to perform actions on multiple events at once. | String | Optional | You can use tags to batch manage events, including: - `delete` : Delete events. - `exclude` : Exclude a date. - `remove_exclude` : Re-add the excluded date. - `skip` : Skip events. - `remove_skip` : Restore skipped events. |
| `zone` | The target multicast zone. | Integer | Optional | Specify the target multicast zone when you have set Multicast Type to one of the following in **Basic Settings** → **Multicast**: - Regular (RTP) - Regular RTP + Poly Group Page - Regular RTP + Poly Push-to-Talk |

**Example:**

```json
{
  "zone": 1,
  "api_call": [],
  "event_type": "play_tone",
  "audio": "bell-na.wav",
  "name": "Lunch Break",
  "auto_remove": 0,
  "enabled": 1,
  "duration": "",
  "rdate": "",
  "tag": "",
  "color": "#ff8800",
  "exdate": "",
  "evid": 1,
  "start_date": "2026-09-01",
  "greyed_out_date": "",
  "rrule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR",
  "extension": "",
  "start_time": "12:00",
  "dtmf": "2",
  "mgroup": "NULL"
}
    
```

##### Event Structure: Stream Audio

This table shows parameters available to the event type **Stream Audio**.

> [!NOTE]
> Note
> 
> The **Stream Audio** event type (`stream_audio`) is available only to 8301.

| **Element** | **Description** | **Type** | **Required** | **Note** |
| --- | --- | --- | --- | --- |
| `api_call` | Specifies the API call(s) to execute. | String | N/A | If an event includes `api_call` entries but its `event_type` is not `api_call`, the associated `api_call` entries are ignored. |
| `audio` | The audio file to play. | String | N/A | Valid values: - Any audio file name that is available in **System** → **File Manager**. |
| `auto_remove` | Deletes all instances of the event or group after it is triggered. | Boolean or `0/1` | Optional | Default value: 0. This can be used to remove temporary schedules intended for testing purposes. |
| `color` | The color of the event to display on the **Calendar**. | String (Hex color value) | Required | If not specified, a unique color is assigned automatically for each new event. |
| `delay` | Postpone the event triggering time in seconds. | Integer | Optional | if specified, the event starts after the specified `delay` period, calculated from the event creation time. - If specified, don’t specify the `start_date` or `start_time`. Otherwise, the schedule fails. - To ensure the event is entered into the Scheduler in time to be activated, set the delay time to at least 10 seconds. |
| `dtmf` | The DTMF tone to play before the tone. | Integer | N/A |  |
| `duration` | The duration of this event in seconds. | Integer | N/A | Don’t specify. It’s generated automatically. |
| `enabled` | Whether this event is enabled. | Boolean or `0/1` | Optional | Default value: 1 |
| `event_type` | The event type. | Enum | Required | Valid value: - `stream_audio` |
| `evid` | The unique ID of the event. | Integer | Optional | Leave it empty to create a new event. Specify the ID to update an existing event. |
| `exdate` | Specifies dates to exclude from the recurrence set generated by `rrule` and `rdate`. | String (YYYY-MM-DD) | Optional |  |
| `extension` | The target SIP extension. | Integer | N/A |  |
| `greyed_out_date` | Days that have skipped events or groups. | String (YYYY-MM-DD) | N/A | Don’t specify. It’s generated automatically. |
| `mgroup` | Poly page group ID. | Integer | N/A | Specify the target Poly page group ID when you have set Multicast Type to one of the following in **Basic Settings** → **Multicast**: - Poly Group Page - Poly Push-to-Talk - Regular RTP + Poly Group Page - Regular RTP + Poly Push-to-Talk |
| `name` | The name of the event. | String | Required |  |
| `rdate` | Specifies additional custom dates on which the event occurs, beyond those defined by `rrule`. | String (YYYY-MM-DD) | N/A | Use commas (,) to separate multiple dates. |
| `rrule` | Defines the recurrence pattern of a repeating event, including the frequency and optional rule components such as `INTERVAL`, `COUNT`, `UNTIL`, and `BYDAY`. | String | Required | Must include `FREQ=`. Valid`FREQ `values: - `DAILY` - `WEEKLY` - `MONTHLY` - `YEARLY` No whitespace allowed. |
| `start_date` | The start date of the event. | String (YYYY-MM-DD) | Required |  |
| `start_time` | The start time of the event. | String (HH-MM:SS) | Required |  |
| `tag` | An optional identifier for events. This identifier can be used to perform actions on multiple events at once. | String | Optional | You can use tags to batch manage events, including: - `delete` : Delete events. - `exclude` : Exclude a date. - `remove_exclude` : Re-add the excluded date. - `skip` : Skip events. - `remove_skip` : Restore skipped events. |
| `zone` | The target multicast zone. | Integer | Optional | Specify the target multicast zone when you have set Multicast Type to one of the following in **Basic Settings** → **Multicast**: - Regular (RTP) - Regular RTP + Poly Group Page - Regular RTP + Poly Push-to-Talk |

**Example:**

```json
{
  "evid": 1,
  "duration": 3600,
  "enabled": 1,
  "rdate": "",
  "dtmf": "",
  "zone": 1,
  "auto_remove": 0,
  "exdate": "",
  "extension": "",
  "audio": "",
  "tag": "",
  "color": "#ffd5de",
  "event_type": "stream_audio",
  "greyed_out_date": "",
  "start_date": "2026-02-26",
  "name": "Lunch Music",
  "rrule": "FREQ=MONTHLY;INTERVAL=2",
  "start_time": "00:00:00",
  "api_call": []
}
```

##### Event Structure: SIP Call with Tone

This table shows parameters available to the event type **SIP Call with Tone**.

| **Element** | **Description** | **Type** | **Required** | **Note** |
| --- | --- | --- | --- | --- |
| `api_call` | Specifies the API call(s) to execute. | String | N/A | If an event includes `api_call` entries but its `event_type` is not `api_call`, the associated `api_call` entries are ignored. |
| `audio` | The audio file to play. | String | Required | Valid values: - Any audio file name that is available in **System** → **File Manager**. |
| `auto_remove` | Deletes all instances of the event or group after it is triggered. | Boolean or `0/1` | Optional | Default value: 0. This can be used to remove temporary schedules intended for testing purposes. |
| `color` | The color of the event to display on the **Calendar**. | String (Hex color value) | Required | If not specified, a unique color is assigned automatically for each new event. |
| `delay` | Postpone the event triggering time in seconds. | Integer | Optional | if specified, the event starts after the specified `delay` period, calculated from the event creation time. - If specified, don’t specify the `start_date` or `start_time`. Otherwise, the schedule fails. - To ensure the event is entered into the Scheduler in time to be activated, set the delay time to at least 10 seconds. |
| `dtmf` | The DTMF tone to play before the tone. | Integer | Optional | Used only when the following configuration is set: **Advanced Settings** → **Advanced Audio** → **Play DTMF Tones Before Pages/Alerts** and set **Alert Specific** for **DTMF Tone(s)**. |
| `duration` | The duration of this event in seconds. | Integer | N/A | Don’t specify. It’s calculated automatically as per the start_time, stop_time. |
| `enabled` | Whether this event is enabled. | Boolean or `0/1` | Optional | Default value: 1 |
| `event_type` | The event type. | Enum | Required | Valid values: - `sip_call` |
| `evid` | The unique ID of the event. | Integer | Optional | Leave it empty to create a new event. Specify the ID to update an existing event. |
| `exdate` | Specifies dates to exclude from the recurrence set generated by `rrule` and `rdate`. | String (YYYY-MM-DD) | Optional |  |
| `extension` | The target SIP extension. | Integer | Required |  |
| `greyed_out_date` | Days that have skipped events or groups. | String (YYYY-MM-DD) | N/A | Don’t specify. It’s generated automatically. |
| `mgroup` | Poly page group ID. | Integer | N/A | Specify the target Poly page group ID when you have set Multicast Type to one of the following in **Basic Settings** → **Multicast**: - Poly Group Page - Poly Push-to-Talk - Regular RTP + Poly Group Page - Regular RTP + Poly Push-to-Talk |
| `name` | The name of the event. | String | Required |  |
| `rdate` | Specifies additional custom dates on which the event occurs, beyond those defined by `rrule`. | String (YYYY-MM-DD) | N/A | Use commas (,) to separate multiple dates. |
| `rrule` | Defines the recurrence pattern of a repeating event, including the frequency and optional rule components such as `INTERVAL`, `COUNT`, `UNTIL`, and `BYDAY`. | String | Required | Must include `FREQ=`. Valid `FREQ `values: - `DAILY` - `WEEKLY` - `MONTHLY` - `YEARLY` No whitespace allowed. |
| `start_date` | The start date of the event. | String (YYYY-MM-DD) | Required |  |
| `start_time` | The start time of the event. | String (HH-MM:SS) | Required |  |
| `tag` | An optional identifier for events. This identifier can be used to perform actions on multiple events at once. | String | Optional | You can use tags to batch manage events, including: - `delete` : Delete events. - `exclude` : Exclude a date. - `remove_exclude` : Re-add the excluded date. - `skip` : Skip events. - `remove_skip` : Restore skipped events. |
| `zone` | The target multicast zone. | Integer | Optional | Specify the target multicast zone when you have set Multicast Type to one of the following in **Basic Settings** → **Multicast**: - Regular (RTP) - Regular RTP + Poly Group Page - Regular RTP + Poly Push-to-Talk |

**Example:**

```json
{
  "duration": "",
  "event_type": "sip_call",
  "start_time": "00:00:00",
  "extension": "1234",
  "exdate": "",
  "evid": 1,
  "dtmf": "",
  "audio": "bell-na.wav",
  "tag": "",
  "api_call": [],
  "color": "#831f8f",
  "auto_remove": 0,
  "enabled": 1,
  "start_date": "2026-02-24",
  "rdate": "",
  "greyed_out_date": "",
  "rrule": "",
  "name": "SIP CALL"
}
    
```

##### Event Structure: API Call

This table shows parameters available to an API call.

| **Element** | **Description** | **Type** | **Required** | **Note** |
| --- | --- | --- | --- | --- |
| `api_call` | Specifies the API call(s) to execute. | String | Required | If an event includes `api_call` entries but its `event_type` is not `api_call`, the associated `api_call` entries are ignored. |
| `actid` | Unique ID for the API Call. | Integer | Required | Leave it empty to create a new event. Specify the ID to update an existing event. |
| `header` | HTTP header content included in the API request. | String | Required | May include authentication headers or predefined variables: - When sending API requests to Algo endpoints that require the **Standard** authentication method, use `%ALGO_HEADERS%` to insert an Algo standard authentication header. ```plaintext "header": "%ALGO_HEADERS%" ``` - When sending API requests to Algo endpoints that require **Basic** authentication, use this header format: ```plaintext "header": "Authorization: Basic <Base64 Value>\\r\\nContent-Type: application/json" ``` Here, the <Base64 Value> is the RESTful API username (admin) and password encoded in Base64. The default **RESTful API Password** is *algo*. - When sending API requests to non-Algo endpoints, refer to their documentation for the authentication header requirements. |
| `method` | HTTP method used for the API request. | String | Required | Common values: `GET`, `POST`, `PUT`, `DELETE`. |
| `name` | User-defined name for the API call. | String | Optional |  |
| `path` | API endpoint path on the target device. | String | Required | Should not include protocol or host (e.g., `api/controls/screen/start`). |
| `payload` | Request body content sent with the API call. | String | Required | Required for methods such as `POST` or `PUT`. Must be valid JSON if provided. |
| `audio` | The audio file to play. | String | Required | Valid values: - Any audio file name that is available in **System** → **File Manager**. |
| `auto_remove` | Deletes all instances of the event or group after it is triggered. | Boolean or `0/1` | Optional | Default value: 0. This can be used to remove temporary schedules intended for testing purposes. |
| `color` | The color of the event to display on the **Calendar**. | String (Hex color value) | Optional | If not specified, a unique color is assigned automatically for each new event. |
| `delay` | Postpone the event triggering time in seconds. | Integer | Optional | if specified, the event starts after the specified `delay` period, calculated from the event creation time. - If specified, don’t specify the `start_date` or `start_time`. Otherwise, the schedule fails. - To ensure the event is entered into the Scheduler in time to be activated, set the delay time to at least 10 seconds. |
| `dtmf` | The DTMF tone to play before the tone. | Integer | Optional | Used only when the following configuration is set: **Advanced Settings** → **Advanced Audio** → **Play DTMF Tones Before Pages/Alerts** and set **Alert Specific** for **DTMF Tone(s)**. |
| `duration` | The duration of this event in seconds. |  | Optional |  |
| `enabled` | Whether this event is enabled. | Boolean or `0/1` | Optional | Default value: 1 |
| `event_type` | The event type. | Enum | Required | Valid values: - `play_tone` - `stream_audio` - `sip_call` - `api_call` |
| `evid` | The unique ID of the event. | Integer | Optional | Leave it empty to create a new event. Specify the ID to update an existing event. |
| `exdate` | Specifies dates to exclude from the recurrence set generated by `rrule` and `rdate`. | String (YYYY-MM-DD) | Optional |  |
| `extension` | The target SIP extension. | Integer | Required |  |
| `greyed_out_date` | Days that have skipped events or groups. | String (YYYY-MM-DD) | N/A | Don’t specify. It’s generated automatically. |
| `mgroup` | Poly page group ID. | Integer | N/A | Specify the target Poly page group ID when you have set Multicast Type to one of the following in **Basic Settings** → **Multicast**: - Poly Group Page - Poly Push-to-Talk - Regular RTP + Poly Group Page - Regular RTP + Poly Push-to-Talk |
| `name` | The name of the event. | String | Required |  |
| `rdate` | Specifies additional custom dates on which the event occurs, beyond those defined by `rrule`. | String (YYYY-MM-DD) | N/A | Use commas (,) to separate multiple dates. |
| `rrule` | Defines the recurrence pattern of a repeating event, including the frequency and optional rule components such as `INTERVAL`, `COUNT`, `UNTIL`, and `BYDAY`. | String | Required | Must include `FREQ=`. Valid `FREQ `values: - `DAILY` - `WEEKLY` - `MONTHLY` - `YEARLY` No whitespace allowed. |
| `start_date` | The start date of the event. | String (YYYY-MM-DD) | Required |  |
| `start_time` | The start time of the event. | String (HH-MM:SS) | Required |  |
| `tag` | An optional identifier for events. This identifier can be used to perform actions on multiple events at once. | String | Optional | You can use tags to batch manage events, including: - `delete` : Delete events. - `exclude` : Exclude a date. - `remove_exclude` : Re-add the excluded date. - `skip` : Skip events. - `remove_skip` : Restore skipped events. |

**Example:**

```json
{
  "api_call": [
    {
      "path": "api/controls/screen/start",
      "payload": "{\n \"type\": \"image\",\n \"image1\": \"alerts-severe-weather-A.png\"\n}",
      "target": "10.11.12.123",
      "method": "POST",
      "header": "%ALGO_HEADERS%",
      "name": "",
      "actid": 1
    }
  ],
  "mgroup": 0,
  "exdate": "",
  "zone": "NULL",
  "evid": 1,
  "rdate": "",
  "rrule": "",
  "auto_remove": 0,
  "start_date": "2026-02-27",
  "tag": "",
  "event_type": "api_call",
  "greyed_out_date": "",
  "audio": "bell-na.wav",
  "start_time": "00:00:00",
  "color": "#f4daf7",
  "duration": "",
  "dtmf": "",
  "extension": "",
  "enabled": 1,
  "name": "Start Screen"
}
```

#### 

##### Group Structure

This table shows parameters available to a group.

| **Element** | **Description** | **Type** | **Required** | **Note** |
| --- | --- | --- | --- | --- |
| `color` | The color of the event to display on the **Calendar**. | String (Hex color value) | Required | If not specified, a unique color is automatically assigned to each new group. |
| `groupid` | The unique ID of the group. | Integer | Optional | Leave it empty to create a new group. Specify the ID to update an existing group. |
| `events` | The list of events. | String | Required | Refer to the following links for the event structure and parameters required by each event type: - [Event Structure: Play Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-play-tone) - [Event Structure: Stream Audio](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-stream-audio) - [Event Structure: SIP Call with Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-sip-call-with-tone) - [Event Structure: API Call](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-api-call) |
| `name` | The name of the event. | String | Required |  |
| `rdate` | Specifies additional custom dates on which the event occurs, beyond those defined by `rrule`. | String (YYYY-MM-DD) | N/A | Use commas (,) to separate multiple dates. |
| `rrule` | Defines the recurrence pattern of a repeating event, including the frequency and optional rule components such as `INTERVAL`, `COUNT`, `UNTIL`, and `BYDAY`. | String | Required | Must include `FREQ=`. Valid`FREQ `values: - `DAILY` - `WEEKLY` - `MONTHLY` - `YEARLY` No whitespace allowed. |
| `start_date` | The start date of the event. | String (YYYY-MM-DD) | Required |  |

**Example:**

```json
 "groups": [
  {
    "rrule": "FREQ=DAILY;INTERVAL=1;UNTIL=20261224T000000Z",
    "groupid": 1,
    "events": [
      {
        <Event1>,
        <Event2>
      }
    ],
    "rdate": "",
    "start_date": "2026-02-24",
    "color": "#f4daf7",
    "name": "Group 1"
  }
]
```

**Related Links:**

Refer to the following links for the event structure and parameters required by each event type:

- [Event Structure: Play Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-play-tone)
- [Event Structure: Stream Audio](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-stream-audio)
- [Event Structure: SIP Call with Tone](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-sip-call-with-tone)
- [Event Structure: API Call](/v1/docs/alpha-2-algo-1344-add-api-to-skip-a-day-in-an-scheduled-event#event-structure-api-call)

#### 

<editor360-custom-block data-preprocessing="true" data-sanitizationtags="div,details,summary,h4,p,ol,li,code,button,strong,em"><editor360-faq data-type="faq"><hr data-faq-hr="true"><div data-expand-collapse="expandFirst" data-faq-type="normal-faq" data-loading="false" data-type="faq-acc-wrapper"><h3 data-block-id="mq1fvqzc-oc0iti-365" id="scheduler-api-faqs">Scheduler API FAQs</h3><div class="details-wrapper details-wrapper_rendered" data-type="details-wrapper"><details data-opened="true" data-button-align="right" data-details-border="withBorder" data-expand-icon="arrow" data-lock="false" open="true"><summary><h4 data-block-id="mq1fryt0-517tbt-340" id="can-i-put-multiple-commands-into-a-single-api-command">Can I put multiple commands into a single API command?</h4></summary><div data-type="details-content"><p data-block-id="mq1fryt0-fk4gg7-341">You can combine multiple POST commands into a single request. For example, you can add a group, remove a standalone event, and skip an instance of another event in one API request. </p><p data-block-id="mq1fryt0-c3cuyt-342">However, regardless of the order in which operations are written in the request, they are executed in the following order:</p><ol data-block-id="mq1fryt0-741kfc-343" start="1" data-start="307" data-end="487" data-is-last-node="" data-is-only-node="" style="--start:0;"><li data-block-id="mq1fryt0-qdpa8b-344" data-start="307" data-end="337"><p data-block-id="mq1fryt0-qi319s-345" data-start="310" data-end="337">Any <code>exclude</code> operation</p></li><li data-block-id="mq1fryt0-gatm39-346" data-start="338" data-end="375"><p data-block-id="mq1fryt0-fpqu0s-347" data-start="341" data-end="375">Any <code>remove_exclude</code> operation</p></li><li data-block-id="mq1fryt0-bv3j15-348" data-start="376" data-end="389"><p data-block-id="mq1fryt1-wrfvtx-349" data-start="379" data-end="389">Any <code>skip</code> operation</p></li><li data-block-id="mq1fryt1-2smlsf-350" data-start="390" data-end="410"><p data-block-id="mq1fryt1-1nn0r7-351" data-start="393" data-end="410">Any <code>remove_skip</code> operation</p></li><li data-block-id="mq1fryt1-ny1fza-352" data-start="411" data-end="426"><p data-block-id="mq1fryt1-jbj1ad-353" data-start="414" data-end="426">Any <code>delete</code> operation</p></li><li data-block-id="mq1fryt1-o62p94-354" data-start="427" data-end="452"><p data-block-id="mq1fryt1-12xgu0-355" data-start="430" data-end="452">Add or update groups</p></li><li data-block-id="mq1fryt1-i5jpfz-356" data-start="453" data-end="487" data-is-last-node=""><p data-block-id="mq1fryt1-lwx6k9-357" data-start="456" data-end="487" data-is-last-node="">Add or update standalone events</p></li></ol></div></details><button class="details-arrow" type="details"></button></div><div class="details-wrapper details-wrapper_rendered" data-type="details-wrapper"><details data-opened="true" data-button-align="right" data-details-border="withBorder" data-expand-icon="arrow" data-lock="false"><summary><p data-block-id="mq1fryt1-np5vmq-358"><strong>How can I quickly locate API request errors in the system log file?</strong></p></summary><div data-type="details-content"><ol data-block-id="mq1fryt1-n06xp4-359" start="1" data-list-format="decimal" style="--start:0;"><li data-block-id="mq1fryt1-jsy45j-360"><p data-block-id="mq1fryt1-wgvdko-361">Go to <strong>System </strong>→ <strong>System Log </strong>→ <strong>Download systlog.txt</strong>. </p></li><li data-block-id="mq1fryt1-6q6nvr-362"><p data-block-id="mq1fryt1-ulh3yw-363">In the <strong>systlog.txt</strong>, search for<strong><em>sched2-load</em></strong> for GET API errors and<em></em><strong><em>sched2-save</em></strong>for POST API request errors.</p></li></ol></div></details><button class="details-arrow" type="details"></button></div></div></editor360-faq></editor360-custom-block>