Summary
The ALIF1100, ALIF2100, ALIF4000 and ALIF102T models provide a RESTful API defined using the OpenAPI specification, enabling the control and configuration of Receivers and Transmitters.
This is not intended to be an exhaustive guide on using APIs. It is assumed that readers are already familiar with REST APIs and the various mechanisms through which they can be accessed.
Resources
The following API resources are available for download:
YAML File:
- Download OpenAPI - RESTful API control
Postman:
- Download Workspace - A pre-built RESTFul API Workspace for testing
What are ETags
The API uses ETags (short for Entity Tag) to ensure that you have the correct status of a device before updating or changing any settings on the Receiver. When requesting a resource, such as a list of Presets, the server sends an ETag header in the response. The ETag is unique to each specific request—for example, requesting a list of presets or devices will return different ETags. To make a change, the ETag must be included in the POST or PATCH request. If the status changes between the initial request and the submission of the change request, the request will be rejected.
For example, when requesting a list of presets, you would use GET https://{RX_IP}/api/presets. The header response will contain the ETag:
Date: Wed, 28 Aug 2024 16:26:56 GMT
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
ETag: "75541d8d1ebac03231d87db3e917c742"
Access-Control-Expose-Headers: ETag
Content-Length: 36
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
ETag: "75541d8d1ebac03231d87db3e917c742"
Access-Control-Expose-Headers: ETag
Content-Length: 36
Once you have the ETag, you will need to store it and add it to the headers as an If-Match header of the POST or PATCH request:
Authorization: {Token}
If-Match: "75541d8d1ebac03231d87db3e917c742"
If-Match: "75541d8d1ebac03231d87db3e917c742"
Tokens
Before you can make any changes to the system, you must log in and retrieve a JWT token. To retrieve a token, you must provide a valid password. By default, this password is set to 'password', but it can be changed on each device. Currently, only one user is supported. A token is valid for 24-hours.
Use POST https://{RX_IP}/users/login/1 with the following text in the body of the request. RReplace the password if you have changed the default, which is empty..
{
"password": "",
"isAdmin": true
}
"password": "",
"isAdmin": true
}
The JSON response will give you AuthToken that you need to store.
{
"authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjEwNzE5NCwiaWF0IjoyMDc5NCwibmJmIjoyMDc5NCwicHJpdmlsZWdlIjoiYWRtaW4iLCJzZXNzaW9uSWQiOiIxIiwidXNlciI6IjAwMDAwMDAwMDEifQ.h8fZKd6to5T60o_hdxBmcRsdKsN_IQjoUxBo9aErEHc"
}
"authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjEwNzE5NCwiaWF0IjoyMDc5NCwibmJmIjoyMDc5NCwicHJpdmlsZWdlIjoiYWRtaW4iLCJzZXNzaW9uSWQiOiIxIiwidXNlciI6IjAwMDAwMDAwMDEifQ.h8fZKd6to5T60o_hdxBmcRsdKsN_IQjoUxBo9aErEHc"
}
Sources and Sinks
Sources and Sinks correspond to the physical connection ports, ie, Video, Audio, USB, and Serial ports. Sources are found on the Transmitter and Sinks are found on the Receiver. Getting the Source and Sink information will give you Port ID's required for setting presets, as well as give you information about the capability of each port.
Control
This section will cover changing channels on an AVM Receiver. The how-to instructions assume you have experience with HTTP-based APIs.
How to Get a List of Presets
To get a list of the current Presets and their Id required to change channels you need to use GET https://{RX_IP}/api/presets..
[
{
"name": "string",
"description": "string",
"connections": [
{
"connectionType": "video",
"sourcePort": 256,
"sinkPort": 256,
"peerUuid": "string"
}
],
"presetId": 4294967295
}
]
{
"name": "string",
"description": "string",
"connections": [
{
"connectionType": "video",
"sourcePort": 256,
"sinkPort": 256,
"peerUuid": "string"
}
],
"presetId": 4294967295
}
]
How to Change Preset
- Make sure you have a Token. See the Tokens section.
- Get the current selected preset ETag:
- Use
GET https://{RX_IP}/api/presets/selected - This will return a JSON with the current preset Id and the ETag in the header
Response HeaderDate: Wed, 28 Aug 2024 16:26:56 GMT
Content-Type: application/json; charset=utf-8
Access-Control-Allow-Origin: *
ETag: "75541d8d1ebac03231d87db3e917c742"
Access-Control-Expose-Headers: ETag
Content-Length: 36
JSON{
"presetId": 1,
"accessMode": "viewOnly"
}
- In this example, Preset Id 1 is currently selected.
- Use
- Using the ETag, you can now change the preset.
- Use
PATCH https//{RX_ID}/api/presets/selected
Add your Authorization Token and ETag to the headers:Authorization: {Token}
If-Match: "75541d8d1ebac03231d87db3e917c742"
In the JSON body, set the Preset Id and the Mode{
"presetId: {ID},
"mode": {mode}
}
- Use
Administrator Tasks
How to add a New Preset:
Adding a new preset includes several steps:
- Make sure you have a Token. See the Tokens section.
- Get the Transmitter UUID
- Use
GET https://{TX_IP}/api/devices - Grab the UUID and IP address of the Transmitter you want to use.
[ { "uuid": "097228ce-9085-41c6-a35c-8da7377ee086", "name": "AVM-C110-CAM-DP 0BD4D8", "description": "Description", "location": "", "serialNumber": "2412A0449220", "type": "TX", "model": "AVM-C110-CAM-DP", "isConfigured": true, "isStatic": false, "isInRecovery": false, "interfaces": [ [ { "ipAddress": "169.254.39.254", "macAddress": "00:0F:58:0B:D4:D8", "ifIndex": 1 } ], [] ] } ]
- Use
- Get the Transmitter Source Ports
- Use
GET https://{TX_IP}/api/sourcesto get a list of source ports from the Transmitter
[ { "type": "video", "ports": [ { "portId": 1, "connectorLabel": "monitor1", "connectorLabelNumbers": [ 1 ], "capabilities": [ { "type": "raw", "subTypes": [ "rgb24" ] }, { "type": "rle", "subTypes": [ "rgb24" ] }, { "type": "afz", "subTypes": [ "24", "a24" ] } ], "connected": false, "enabled": true, "frameSkipping": 0, "backgroundRefresh": 32, "magicEye": { "enabled": false, "overrides": [] }, "maxBitsPerPixel": 24, "supportedBitsPerPixel": [ 24 ], "compressionType": "pixelPerfect", "minCompression": "", "maxCompression": "", "edidOptimisation": true, "edidSourceFixed": "Attached monitor", "edidSourceDynamicRangeFixed": "SDR8 (8bpc)", "edidSourceUuid": "", "multicastAddresses": [ "239.255.1.33", "" ] }, { "portId": 2, "connectorLabel": "monitor2", "connectorLabelNumbers": [ 2 ], "capabilities": [ { "type": "raw", "subTypes": [ "rgb24" ] }, { "type": "rle", "subTypes": [ "rgb24" ] }, { "type": "afz", "subTypes": [ "24", "a24" ] } ], "connected": false, "enabled": true, "frameSkipping": 0, "backgroundRefresh": 32, "magicEye": { "enabled": false, "overrides": [] }, "maxBitsPerPixel": 24, "supportedBitsPerPixel": [ 24 ], "compressionType": "pixelPerfect", "minCompression": "", "maxCompression": "", "edidOptimisation": true, "edidSourceFixed": "Attached monitor", "edidSourceDynamicRangeFixed": "SDR8 (8bpc)", "edidSourceUuid": "", "multicastAddresses": [ "239.239.1.33", "" ] } ] }, { "type": "audio", "ports": [ { "portId": 1, "connectorLabel": "usb", "connectorLabelNumbers": [], "capabilities": [ { "type": "analogue", "subTypes": [ "stereo" ] } ], "enabled": true, "connected": true, "qualityMode": "auto", "multicastAddresses": [ "239.223.1.33", "" ] }, { "portId": 2, "connectorLabel": "monitor1", "connectorLabelNumbers": [ 1 ], "capabilities": [ { "type": "digital", "subTypes": [ "lpcm" ] } ], "enabled": true, "connected": false, "edidOptimisation": true, "edidSourceFixed": "Attached monitor", "edidSourceUuid": "", "multicastAddresses": [ "239.207.1.33", "" ] }, { "portId": 3, "connectorLabel": "monitor2", "connectorLabelNumbers": [ 2 ], "capabilities": [ { "type": "digital", "subTypes": [ "lpcm" ] } ], "enabled": true, "connected": false, "edidOptimisation": true, "edidSourceFixed": "Attached monitor", "edidSourceUuid": "", "multicastAddresses": [ "239.191.1.33", "" ] }, { "portId": 4, "connectorLabel": "lineIn", "connectorLabelNumbers": [], "capabilities": [ { "type": "analogue", "subTypes": [ "stereo" ] } ], "enabled": true, "connected": false, "qualityMode": "auto", "multicastAddresses": [ "239.175.1.33", "" ] } ] }, { "type": "usb", "ports": [ { "portId": 1, "connectorLabel": "usb", "connectorLabelNumbers": [], "capabilities": [ { "type": "emulated", "subTypes": [ "standard" ] } ], "connected": false, "enabled": true, "virtualKeyboard": true, "hubSize": "13", "security": "on", "numReservedVirtualHubPorts": 0, "primaryEmulatedPort": false } ] }, { "type": "serial", "ports": [ { "portId": 1, "connectorLabel": "auxUsb", "connectorLabelNumbers": [], "capabilities": [ { "type": "RS-232", "subTypes": [ "standard" ] } ], "enabled": true, "connected": false, "parity": "none", "dataBits": 8, "stopBits": 1, "speed": 115200 } ] } ]
- Use
- Get the Receiver Sink Ports
- Use
GET https://{RX_IP}/api/sinks
[ { "type": "video", "ports": [ { "portId": 1, "connectorLabel": "monitor1", "connectorLabelNumbers": [ 1 ], "capabilities": [ { "type": "raw", "subTypes": [ "rgb8", "rgb16", "rgb24" ] }, { "type": "rle", "subTypes": [ "rgb16", "rgb24" ] }, { "type": "afz", "subTypes": [ "24", "a24" ] } ], "enabled": true, "connected": true, "compatibilityCheck": true, "freezeImageOnLoss": false, "frameRateSwitching": "retain" }, { "portId": 2, "connectorLabel": "monitor2", "connectorLabelNumbers": [ 2 ], "capabilities": [ { "type": "raw", "subTypes": [ "rgb8", "rgb16", "rgb24" ] }, { "type": "rle", "subTypes": [ "rgb16", "rgb24" ] }, { "type": "afz", "subTypes": [ "24", "a24" ] } ], "enabled": true, "connected": false, "compatibilityCheck": true, "freezeImageOnLoss": false, "frameRateSwitching": "retain" } ] }, { "type": "audio", "ports": [ { "portId": 1, "connectorLabel": "headsetLineOut", "connectorLabelNumbers": [], "capabilities": [ { "type": "analogue", "subTypes": [ "stereo" ] } ], "enabled": true, "connected": false, "gain": "mic" }, { "portId": 2, "connectorLabel": "monitor1", "connectorLabelNumbers": [ 1 ], "capabilities": [ { "type": "digital", "subTypes": [ "lpcm" ] } ], "enabled": true, "connected": true, "compatibilityCheck": true }, { "portId": 3, "connectorLabel": "monitor2", "connectorLabelNumbers": [ 2 ], "capabilities": [ { "type": "digital", "subTypes": [ "lpcm" ] } ], "enabled": true, "connected": false, "compatibilityCheck": true } ] }, { "type": "serial", "ports": [ { "portId": 1, "connectorLabel": "usb1to4", "connectorLabelNumbers": [ 1, 2, 3, 4 ], "capabilities": [ { "type": "RS-232", "subTypes": [ "standard" ] } ], "enabled": true, "connected": true } ] }, { "type": "usb", "ports": [ { "portId": 1, "connectorLabel": "usb1to4", "connectorLabelNumbers": [ 1, 2, 3, 4 ], "capabilities": [ { "type": "emulated", "subTypes": [ "standard" ] } ], "enabled": true, "hidOnly": false, "disableMassStorage": false, "isochronousDevices": true, "security": "preferOff", "connectorVideoMap": [ 1, 2, 1, 2 ], "connectorReservations": [ { "disableMerge": false, "sourceVirtualHubPortNumber": 0 }, { "disableMerge": false, "sourceVirtualHubPortNumber": 0 }, { "disableMerge": false, "sourceVirtualHubPortNumber": 0 }, { "disableMerge": false, "sourceVirtualHubPortNumber": 0 } ] } ] } ]
- Use
- Add the Preset to the Receiver
- Get the current ETag by using
GET https://{RX_IP}/api/presets - Add the token and ETag to the headers
- Using the Transmitter UUID, Source Ports, and Sink Ports, create the JSON for the preset
{ "name": "Example", "description": "Example Preset", "connections": [ { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "video", "sourcePort": 1, "sinkPort": 1 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "video", "sourcePort": 2, "sinkPort": 2 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "audio", "sourcePort": 1, "sinkPort": 1 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "audio", "sourcePort": 2, "sinkPort": 2 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "audio", "sourcePort": 3, "sinkPort": 3 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "usb", "sourcePort": 1, "sinkPort": 1 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "serial", "sourcePort": 1, "sinkPort": 1 } ] }
- On a successful POST, this will return a Preset ID:
{
"presetId": 7
}
- Get the current ETag by using
- Add the Preset to the User's Preset List
- Get the current ETag for the User's Preset List
GET https://{RX_IP}/api/users/presets/{userID} - Add the Token and ETag to the request headers
- Use the PresetID that was generated from the last step in the JSON Body
- Use
POST https://{RX_IP}/api/users/presets/{userID}
{ "hotkeyNumber": 7, "viewOnly": true, "shared": true, "exclusive": true, "private": true, "presetId": 7 }
- A 204 response will be returned on a successful result
- Get the current ETag for the User's Preset List
Modifying Existing Preset:
- Make sure you have a Token. See the Tokens section.
- Get the presets ETags:
- Use
GET https://{RX_IP}/api/presets/{PresetID} - This will return a JSON with the requested preset information and the ETag in the header
- Use
- Once you have the Token and ETag required proceed with
PATCH https://{RX_IP}/api/presets/{PresetID}- Using PATCH, you can just specify the specific data you want to replace. An example of replacing all the data is below:
{ "name": "Example_Edit_2", "description": "Example Edit", "connections": [ { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "video", "sourcePort": 1, "sinkPort": 1 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "video", "sourcePort": 2, "sinkPort": 2 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "audio", "sourcePort": 1, "sinkPort": 1 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "audio", "sourcePort": 2, "sinkPort": 2 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "audio", "sourcePort": 3, "sinkPort": 3 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "usb", "sourcePort": 1, "sinkPort": 1 }, { "peerUuid": "1c563b20-5ddc-4e65-b4ea-7c003f0feccd", "connectionType": "serial", "sourcePort": 1, "sinkPort": 1 } ] }
- Using PATCH, you can just specify the specific data you want to replace. An example of replacing all the data is below:
- A successful modification will return a 204 response.
How to Delete a Preset:
- Make sure you have a Token. See the Tokens section.
- Get the presets ETags:
- Use
GET https://{RX_IP}/api/presets/{PresetID} - This will return a JSON with the requested preset information and the ETag in the header
- Use
- With the ETag and Token use
DELETE https://{RX_IP}/api/presets/{PresetID}
- A successful deletion will return a 204 response