About

info-beamer.com exposes most of its functionality through an HTTP REST API. You can use this API to, for example, change setup configuration values, assign setups to devices or more. You can even build your own digital signage frontend and use the solid foundation of info-beamer hosted to manage your devices.

Note that this is the documentation for the info-beamer.com API. Take a look at the info-beamer Lua API documentation if you're interested in writing your own Lua code for the info-beamer player software itself.

Intro

All examples in this documentation use curl syntax together with the tool jq. Most programming languages should have easy to use http client libraries and you should be able send your requests with them easily. Get in contact if you need help.

The info-beamer API base url is

https://info-beamer.com/api/v1/

As you can see the API is versioned. Right now there is only v1 active. Changes to this version won't introduce any breaking changes. But additional information might get included in responses. So your client library should at least be able to ignore those (see also).

Endpoints that change the state of any info-beamer object require a POST or DELETE requests. Some endpoints merely query data so they use GET requests. Content for POST requests is given in application/x-www-form-urlencoded or multipart/form-data encoded format.

Authentication

Most API calls require authentication. There are three different methods of authentication:

• You can use one of your API keys. Each access in you account provides an API key that is restricted according to the attached ACL.
• You can use the sessions API calls or use OAuth to create a new sessions. You'll get a new temporary API key that can issue API calls on behalf of an access.
• adhoc API keys are programmatically created API keys with an very limited life time, usage count and optionally an added policy. They are intended to be handed directly to a user to issue requests on behalf of an access while not exposing the API key directly.

Regardless of which method you use, you can send the API key as the password of a basic auth request. You must leave the username empty. If your http client for any reason doesn't support empty usernames, you can also use "api" instead.

In curl this might look like this:

curl -u :$API_KEY https://info-beamer.com/api/v1/ping | jq .

You can also use the Bearer authentication by sending an Authentication request header like this:

Authorization: Bearer ${API_KEY}

with API_KEY being your API key. Alternatively you can also use the api-key url parameter for authentication but this is usually not recommended as url parameters end up in the browser history. You should only use this option for API keys with very limited permissions, for example when issuing check calls from a monitoring system.

Insecure access

You must always use encrypted connections when using the API. Be sure to prefix your API requests with https. Do not use http as that's insecure and will leak your access key to anyone able to monitor your network connection.

info-beamer will detect insecure API usage and instantly marks the API key as compromised (See the compromised boolean within the list of shares). API keys marked as compromised will still work when accessing your own account but will no longer work when accessing other accounts shared with you.

It is highly recommended that you renew the API key before trying to use the API again.

Stability

Our goal with the API is to provide a stable and long lasting environment for you to work with. We'll do our best to avoid the constant update cycle and needless busywork other APIs might require from you. Once you build an integration with our API, you can be sure that you won't have to update it for a long time, if ever. If we're ever forced to retire an endpoint, we'll let you know at least one year in advance.

We might add new API endpoints and add new fields to existing responses, but won't remove any field without prior notice and will get in contact with you to see how to handle that.

Note that undocumented fields within API responses should be considered to be unreliable as they might change at any time and we cannot make any promises about them. This might happen while we slowly roll out a new work-in-progress feature. Only rely on documented fields. When in doubt, please get in contact.

The same policy applies to undocumented API endpoints. The info-beamer dashboard uses the same API documented here and some features might be available as a preview to a subset of users. While such a preview is in progress, the API for such a new feature might still change in backwards incompatible ways. Once a feature is considered stable and reliable, documentation will be added. Only then rely on such endpoints.

Quotas

Some resources (like devices, setups, packages or assets) have a quota attached to them. This means that you can only create a limited total number of them. Once you reach this number, trying to create another object will result in an error when calling the API. You can query your account quotas using the 'Get account information' API call. It returns all quotas with their current value and limit.

The default quotas are sufficient for 99% of info-beamer's use cases and prevent runaway API usage that might have impact on other customers. In exceptional circumstances we might raise the quota. Please contact support with a description why you need more than the defaults.

Rate Limits

The info-beamer API is subject to rate limits. Each account has a sustained limit of a total of 300 calls/minute (that's 5/s) across all API endpoints:

Exceeding this global limit will immediately return a HTTP status 429 response. See below. Additionally individual endpoints are subject to dedicated rate limits. All limits are implemented as a leaky bucket algorithm with a possible burst factor of 200%.

Here's an example of an endpoint with a 20 requests/minute limit: There is a virtual "bucket" that has space for 40 drops, that is 200% of 20. Each API calls fills the bucket with one drop. Once the bucket is full, a 429 response is returned and the API call denied. At a constant rate of 20 drops per minute the bucket slowly leaks, opening up space for more API calls. Essentially this means such an endpoint can be called at a sustained rate of 20 requests/minute. A sudden burst of API calls is permitted as long as the overall average doesn't exceed 20 requests/minute.

Requests not exceeding the rate limit include the following HTTP response headers:

For requests exceeding the rate limit a 429 response is returned and the following headers are set and the request should be retried after a delay. The recommended delay is returned in the Retry-After response header value:

We closely monitor how the API is used and reserve the right to impose limits as we see fit. Both to prevent abuse as well as to prevents problems for other customers. Most use cases do not require excessive amounts of API calls. Please get in contact if you need hints on how to use the API.

General hints are:

• Only call the API if you actually need to change anything.
• Use the userdata feature to add state to objects on the info-beamer side of the API that helps you decide if you need to make a call.
• Don't query individual devices/setups/assets in rapid succession if you can use a single /list call.
• Don't repeatedly call /list APIs unless you have a reason to assume that anything has actually changed between calls.
• Don't be lazy. A brute force approach might work for a few devices but won't scale as you might run into rate-limits later. Implement your system properly from the start.

Testing rate limits

It is highly recommended that you implement a retry logic for all API calls and transparently handle rate limited calls. Use the number of seconds returned in the Retry-After response header to delay repeated requests. You can use the following testing endpoints to verify your code. These endpoints share a 5 requests/60 seconds (or 10 request/60 seconds burst) rate and just return a dummy value response.

GET https://info-beamer.com/api/v1/test/rate-limit
POST https://info-beamer.com/api/v1/test/rate-limit
DELETE https://info-beamer.com/api/v1/test/rate-limit

Last-Modified support

Currently the Setup detail/update and Playlist detail/update API calls return a Last-Modified response header and support conditional POST requests using the If-Unmodified-Since request header. If the modified object has been changed since the specified date, the request will fail with a 412 Precondition failed response and changes will not be applied.

CORS

You can use the info-beamer API within a browser from other origins using the CORS mechanism with the following restriction:

You must issue those calls from a HTTPS origin. It's not possible to use insecure HTTP origins to query the API except when using localhost for development purposes. When deploying your JS based API client, use HTTPS.

Insecure HTTP origins are not supported as anyone observing your HTTP traffic might tamper with your API calls or access the API key used for your calls.

If you want to restrict API access based on the origin, you can create an ACL restricting access based on the request:origin:host request context.

Responses

Devices

You can fully manage a device lifecycle through the API. You can create devices, change their settings, query or reboot them and of course delete them. Devices can show a single setup at a time. Devices are represented by their device_id.

Create a new device

POST https://info-beamer.com/api/v1/device/create

{
  "Statements": [
    {
      "Action": "device:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Assign a device to an account. The PIN shown on the device welcome screen must be given.

If there is a default setup selected for your account or you provide a setup id in the request parameters it will be automatically installed on the new device. Otherwise the device will stay on the welcome screen and wait until a setup is assigned later.

Request parameters

Response

Example

curl -u :API_KEY https://info-beamer.com/api/v1/device/create -d "pin=12345678" | jq .

List devices

GET https://info-beamer.com/api/v1/device/list

{
  "Statements": [
    {
      "Action": "device:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

List devices assigned to an account.

Response

Device Object

A Device Object is returned in both the devices list and the device details API call. A Device Object has the following format:

Maintenance Flags

The maintenance list in a device object can contain multiple string. Each of them shows a detected problem of a device. Possible values are given in the following table. Additional flags might be added in the future.

Run Object

Information about the device as gathered when the device contacts the info-beamer hosted service.

Example

curl -u :$API_KEY https://info-beamer.com/api/v1/device/list | jq .

Device details

GET https://info-beamer.com/api/v1/device/<device_id>

{
  "Statements": [
    {
      "Action": "device:detail",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request information about an individual device.

Response

Returns a device object. The device_id is expected to be an Integer value. You can get those ids in the devices list request.

Device telemetry

GET https://info-beamer.com/api/v1/device/<device_id>/telemetry

{
  "Statements": [
    {
      "Action": "device:detail:telemetry",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request telemetry information about a device during the last 24 hours of the device being online.

Response

Device snapshot

GET https://info-beamer.com/api/v1/device/<device_id>/output

{
  "Statements": [
    {
      "Action": "device:detail:output",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request a screen capture of the device. This request might take a moment. The device_id is expected to be an Integer value. You can get those ids in the devices list request.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

Response

Device sensor info

GET https://info-beamer.com/api/v1/device/<device_id>/sensor

{
  "Statements": [
    {
      "Action": "device:detail:sensor",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Requests various pieces of (realtime) information about a device. The device_id is expected to be an Integer value. You can get those ids in the devices list request.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

Response

Device reboot

POST https://info-beamer.com/api/v1/device/<device_id>/reboot

{
  "Statements": [
    {
      "Action": "device:reboot",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Reboot a device. The device_id is expected to be an Integer value. You can get those ids in the devices list request.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

Response

Device location

GET https://info-beamer.com/api/v1/device/<device_id>/location

{
  "Statements": [
    {
      "Action": "device:location:update",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Try to get the device location based on WiFi and/or IP information. The device_id is expected to be an Integer value. You can get those ids in the devices list request.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

The lat and lon values are saved if a location could be detected and are available in the geo field in Device Objects returned by the device list or device detail calls.

Response

POST https://info-beamer.com/api/v1/device/<device_id>/location

{
  "Statements": [
    {
      "Action": "device:location:update",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

The set lat and lon values are available in the geo field in Device Objects returned by the device list or device detail calls.

Request parameters

Response

DELETE https://info-beamer.com/api/v1/device/<device_id>/location

{
  "Statements": [
    {
      "Action": "device:location:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Removes a stored lat and lon device location previously generated from an earlier GET request.

Response

Device OS channel

POST https://info-beamer.com/api/v1/device/<device_id>/channel

{
  "Statements": [
    {
      "Action": "device:switch-channel",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Update a device to the latest OS release within a OS release channel. The device will download the requested OS version in the background, apply the update and finally reboot. The downtime is limited to the time it takes the device to reboot which is usually only 10 - 20 seconds.

The normal A/B failsafe mechanism is used, so if the device doesn't reconnect back to the info-beamer service after 6 minutes, it will reboot again into the previous OS channel/version.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout for triggering the update. The updating itself might take longer as it depends on download speed and various other factors.

If you want to just upgrade a device to the latest version within its current channel, use the config call below with an POST an empty configuration.

Request parameters

Response

Device config

GET https://info-beamer.com/api/v1/device/<device_id>/config

{
  "Statements": [
    {
      "Action": "device:config:read",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Fetches the current device configuration. That is: The content of the files set in the /config directory. See device configuration for details about files within /config and their content.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

This call returns information on all files in the /config directory. The returned dictionary contains all filenames mapped to their content. As files can in theory contain arbitrary binary content, all the values are base64 encoded. The content of files larger than 8K is not included in the response. Instead the file size (an integer value) of such files is returned instead of their content.

Response

POST https://info-beamer.com/api/v1/device/<device_id>/config

{
  "Statements": [
    {
      "Action": "device:config:write",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Allows you to set a new configuration to a device. The device will install the most recent OS version in its channel (e.g. `stable`) and apply the given configuration. If you provide an empty configuration, the device's configuration will be untouched while the device is upgraded to the lastest OS version. Upgrading and applying the configuration is done in the background. Once that's done the device reboots. The expected downtime is limited to the time it takes the device to reboot which is usually only 10 - 20 seconds.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

A/B failsafe mechanism

An A/B failsafe mechanism is used, so if the device doesn't reconnect back to the info-beamer service after 6 minutes, it will reboot into the previous working version. This will reverse all configuration changes made but ensures a device remains usable even if an invalid configuration or non-working OS update was applied.

Any configuration or OS change will always result in a completely new version of the OS with the new settings added. Except for the configuration itself, there are never leftovers from any previous installation.

This process usually takes between 30 seconds and a few minutes, depending on whether or not the latest OS version is already locally available. The device remains fully functional while it's applying the update in the background. Once the installation is complete, the device will reboot into a "trial" version of the new configuration to see if the new settings work. Working in that case means that the device

• gets a connection to info-beamer.com
• gets a proper system time
• the info-beamer process runs for at least 10 seconds

If any of those tests doesn't pass within 6 minutes or the power is removed before passing all tests, the system automatically reverts into the previously running version by rebooting again. If you apply any kind of configuration update or OS upgrade, always make sure the device reboots while still connected to the internet and give it 1-2 minutes to ensure it has enough time to confirm the trial boot.

If you change a configuration and immediately disconnect power after the device reboots, the device sees that as a failed setting change and all changes are rolled back. This is to prevent you from accidentally setting (for example) a wrong WiFi network. If this mechanism wasn't there, you would lose access to the device after such a change forever and would have to physically revert the settings by editing the configuration files on the SD card. This mechanisms cannot be deactivated and is always used for configuration changes and OS upgrades.

Request parameters

files will remain unchanged. The maximum size of each config value is 8K. |

Response

Device node command

POST https://info-beamer.com/api/v1/device/<device_id>/node/<path>

{
  "Statements": [
    {
      "Action": "device:node-message",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Posts a message to the device that ends up being sent to the running info-beamer code through a locally delivered UDP message. You can react to that message within Lua using the util.data_mapper or node.event/data functions.

The maximum combined size of the path and data value should not exceed 1400-1500 bytes total as otherwise the data value might be truncated. Only use this feature to send small pieces of information to a device.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

Request parameters

The <path> value within the url determines the complete path the is used in the UDP packet sent to the device. If you want to address the top-level node, use root.

Once the request reaches the device it is translated to a UDP packet sent to locally running info-beamer process on port 4444 with the following content:

<path>:<data>

Response

Note that this doesn't necessarily mean that the running Lua code successfully handled the event. info-beamer might just be restarting or there might be an error in the code that handles the event. A success message only means that the device has acknowledged that it has received and forwarded the data through a UDP packet. You should never rely on a successful delivery.

Device service command

POST https://info-beamer.com/api/v1/device/<device_id>/service/<path>

{
  "Statements": [
    {
      "Action": "device:service-message",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Similarly to node commands, this posts a message to the device that potentially ends up being sent to a package service running on the device through a locally delivered UDP message. The package service must bind to the UDP port provided to it by the SERVICE_DATA_PORT environment variable.

The maximum combined size of the path and data value should not exceed 1400-1500 bytes total as otherwise the data value might be truncated. Only use this feature to send small pieces of information to a device.

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

Request parameters

The <path> value within the url determines the complete path the is used in the UDP packet sent to the device.

Once the request reaches the device it is translated to a UDP packet sent to locally to a package service proces. If multiple services are running at the same time, the service matching the longest prefix within the provided path will receive the message with the remainder of the path being included in the sent UDP packet. So if use a path like root/something, the following content is sent to the top-level service:

something:<data>

Response

Note that this doesn't necessarily mean that the event got handled by the service or that it got indeed delivered. The package service might be restarting due to some error or might not be listening to UDP at all. You should never rely on a successful delivery.

Device session

POST https://info-beamer.com/api/v1/device/<device_id>/session

{
  "Statements": [
    {
      "Action": "device:session",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Initiate a terminal session with the device. This will spawn a new shell on the command and allows you to connect to that shell using a websocket connection. This is used for the Remote Terminal feature on the device detail page. Once the viewer disconnects, all launched processes will be killed (using SIGKILL).

This requests requires the hosted service to contact the device. So this request might take a moment before it returns. There is a maximum 30 second timeout.

Do not use this feature to automate anything on your devices. It's purely provided for interactive debugging on a device and the number of concurrent connection can be limited in the future without prior notice.

Request parameters

Response

Session protocol

Connect to the endpoint value of the response using a websocket connection. There is a timeout of around 60 seconds after which the device stops the terminal server and you won't be able to connect. So don't wait too long after creating a session.

All data is encapsulated in JSON packets. The initial packet will be as follows. It might take a moment to arrive as the device has to spawn the terminal server first:

{"event": "connected"}

This means that your websocket connection is now connected to the device. You'll now have to send a setup command to start the shell with the requested terminal size:

{"event": "setup", "rows": 25, "cols": 80}

This will spawn a new /bin/sh instance in a terminal of the requested size. You cannot change the terminal size later.

At this point you'll receive the terminal output of the shell with packets like this:

{"event": "data", "data": "<output>"}

You should directly feed this data into your terminal emulator. The only other event generated right now is:

{"event": "eof"}

at which point you can close your websocket connection. Your client should ignore unknown events.

Your websocket client can send the two packets as follows to control the remote terminal:

{"event": "stdin", "data": "<input>"}

This sends data to the stdin of the terminal process. Similarly you should send a keepalive command from time to time to ensure the connection stays alive even if the device is behind a NAT. Every 30 seconds is recommended:

{"event": "keepalive"}

Have a look at https://github.com/info-beamer/package-sdk/tree/master/ib-shell for an example client in Python. If you prefer a browser based client, consider using https://xtermjs.org/

Update device

POST https://info-beamer.com/api/v1/device/<device_id>

Update an individual device. The device_id is expected to be an Integer value. You can get those ids in the devices list request.

The required permissions and rate limits depend on the updates made. See below for more information.

Request parameters

Conditional permissions

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "device:update:userdata",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:location",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:description",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:setup",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:reboot",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:mark-fixed",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:offline-plan",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:suspend",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:upgrade-blocked",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:device-data",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Conditional rate limits

Depending on which request parameters are set, the following policy actions are triggered:

Response

The response only indicates that the changes were received by info-beamer hosted. It might take a moment for a new setup to become active after you assign it to a device. You can use the is_synced information in the device object to find out if a device is in sync.

Example

curl -u :$API_KEY https://info-beamer.com/api/v1/device/1234 -d location=office&description=My%20Pi

Delete device

DELETE https://info-beamer.com/api/v1/device/<device_id>

{
  "Statements": [
    {
      "Action": "device:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Deletes a device. The device_id is expected to be an Integer value. You can get those ids in the devices list request.

Deleting a device removes it from your account. Unless there is a Device Connect Key configured (see below), your device will reboot and anyone that can see the screen can add it to their account.

When you delete a device it will reboot. By default it will then show a PIN that can use used to connect the device to your account. Anyone that has this PIN can do that. You can also make devices automatically join your account using a Device Connect Key.

Response

Example

curl -X DELETE -u :$API_KEY https://info-beamer.com/api/v1/device/1234

Schedules

Schedules will be documented once their API is considered stable.

Setups

Setups are a collection of at least a single package and the associated configuration. A setup can be installed on devices. Setups can consist of multiple package instances 'mounted' to different paths within a setup. When you create a new setup, the given package is mounted at /. You can assign or remove additional packages in subdirectories. As each package itself can contain multiple nodes, the resulting tree contains all nodes from all packages.

The following example can hopefully help you understand the relationship between packages, their nodes and how instances of packages are used within a setup. Have a look at this example. This is a setup configuration interface. You might have seen that in the details page of a setup already:

This setup uses the HD Image/Video Player package as it's root package. This package only has a single node named Player. It's complete path within the setup is /. Additionally another package has been added to the setup: The Power Saver package. It was added at the /power path. As the Power Saver package only has a single node, this node ends up at /power. When installing this setup on a device, the files for the toplevel (/) node end up in the directory that is displayed on the device. Below that, in the power directory, you'll find the node files of the power saver node.

This package has two package instances. One for the HD Image/Video Player and one for the Power Saver package. Every setup must have at least one package instance at the root of the tree (/). It can then have multiple child package instances. They can also be nested.

Create a new setup

POST https://info-beamer.com/api/v1/setup/create

{
  "Statements": [
    {
      "Action": "setup:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This request will create a new setup based on a given package at its root.

Request parameters

Response

List setups

GET https://info-beamer.com/api/v1/setup/list

{
  "Statements": [
    {
      "Action": "setup:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Lists setups in an account.

Response

Setup Info Object

This API call returns a list of setup info objects that give you basic information about each configured setup. The following fields are present in all returned objects:

Setup details

GET https://info-beamer.com/api/v1/setup/<setup_id>

{
  "Statements": [
    {
      "Action": "setup:detail",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request information about an individual setup. The setup_id is expected to be an Integer value. This API call returns how the setup is put together - for example what packages are used and which assets are provided by the setup. It also returns information about all configuration options, so you can build a dynamic configuration interface for this setup. Finally it returns the current configuration.

Response

Setup Instance Object

Each setup can have one or more packages assigned to it. An instance object describes these instances and their relationship to each other.

Package Info Object

This object describes a package. Most of the content is derived from values provided in the package.json file of the package. The following fields are provided:

Setup Node Object

This object provides information about an individual node of a setup. A setup will have at least one node at the top level (/). There can be multiple nodes if either the single top-level package contains multiple nodes or if multiple packages are used within the setup.

Setup Asset Info Object

If a setup includes a resource option the user can select either one of their own assets. Or, if the package includes asset compatible files, they also have the ability to choose those. The setup detail API call returns those additonal assets for each node of a setup. The following information is provided:

Update setup

POST https://info-beamer.com/api/v1/setup/<setup_id>

You can update an existing setup: You can change its name, attach userdata or update the configuration for all or individual nodes.

While setup changes are usually synced pretty quickly to a device, you should not rely on that. You should also keep the setup change update rate at a sensible level. Do not use this API to push real time information to your device. Instead use the 'Device command' feature for that.

Request parameters

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "setup:update:userdata",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "setup:update:config",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "setup:update:name",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

If you set a new config, you usually have to provide a complete configuration objects for all nodes of this setup. The configuration will have to have the same structure as the value of the config field in the setup details response.

If you update the configuration of a setup that is assigned to a device, the device will automatically fetch those changes and activate them.

If you only want to update some part of a setup, you can also specify the mode "update". This will merge the new configuration with the existing configuration: The existing configuration is used and updated with all values given as the new configuration. This can be used to update parts of an existing configuration without touching the rest. For example if you want to update the "name" option of the top-level node "", you can send the following new configuration json:

{"": {"name": "foo"}}

Using curl, the request might looks like this:

curl -u :$API_KEY https://info-beamer.com/api/v1/setup/42
    -d 'config={"":{"name":"foo"}}&mode=update'

Updating an existing setup in "update" mode allows even more complicated merges. If your package uses list options you can also selectivly update values within lists. Here's an example:

curl -u :$API_KEY https://info-beamer.com/api/v1/setup/42
    -d 'config={"":{"items":[{}, {"text":"foo"}]}}&mode=update'

This will update the "items" option list in the top level node. It will leave the first item in that list unchanged (thanks to the empty {}). The second element in that list has its "text" value updated to "foo". Any further elements originally in the "items" list will be removed.

Response

Attach package instance

POST https://info-beamer.com/api/v1/instance/create

{
  "Statements": [
    {
      "Action": "instance:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

A setup consists of one or many packages. There is always a top level package and zero or more packages recursively attached to this top level package. It is of course possible to use the same package multiple time in the same setup.

You can think of a Setup as a collection of individual filesystems (Packages), each with their own directory structure (each directory is a Node) mounted into a single virtual filesystem tree. This API call attaches one of your package to an existing package instance in one of your setups. Reusing the filesystem analogy: You mount a package as a child of an existing Node in the virtual filesystem tree.

Request parameters

Response

Delete package instance

DELETE https://info-beamer.com/api/v1/instance/<instance_id>

{
  "Statements": [
    {
      "Action": "instance:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This will delete the given package instance. The instance cannot be deleted if it is the top level package for a setup. It also cannot be deleted if it is referenced in the configuration of its parent node.

If the instance itself has additional child instances, they will be removed from the setup as well.

Response

Delete setup

DELETE https://info-beamer.com/api/v1/setup/<setup_id>

{
  "Statements": [
    {
      "Action": "setup:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This will delete a setup. You cannot delete a setup if it is still used on a device. You can check the used information in a Setup Info Objects to find out on how many devices a setup is currently used.

Packages

A package is a collection of info-beamer nodes together with a description of how they can be configured. You can read more about packages on the package reference. Packages cannot be directly install on a device as they have to be configured through a setup.

Create a new package

POST https://info-beamer.com/api/v1/package/create

{
  "Statements": [
    {
      "Action": "package:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request parameters

Each package created on info-beamer hosted must be imported from somewhere. There are different possible ways of preparing a package for import into info-beamer hosted. If the source parameter is omitted, a new git repository is created. Otherwise the package is imported from the given urls. The package is validated to make sure that is is syntactially correct.

If you submit the value "full" as asset_check, info-beamer hosted will run additional validations on the package files: Images (png/jpg) and videos (mp4) are checked to make sure that info-beamer is able to play those files. Once set, this option cannot be changed and will also be active while updating the package.

Response

List packages

GET https://info-beamer.com/api/v1/package/list

{
  "Statements": [
    {
      "Action": "package:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Package Object

The object for each package in the package list API call has the following elements:

Package details

GET https://info-beamer.com/api/v1/package/<package_id>

{
  "Statements": [
    {
      "Action": "package:detail",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request information about an imported package. The package_id is expected to be an Integer value.

Response

Package Version Object

Version information for a package. The package version is taken from the package.json file.

Each day, info-beamer hosted will automatically pull the package source to see if there is an update available. If the current package version is different from the version of the source (as specified in the package.json file), this object will contain information about the update.

Likewise this object is used to describe the current release of a package if the package provides version information in the package.json file.

Package File Object

Gives information about an individual files in a package.

Package Node Object

Describes a node within a package. A node is a directory with the ability to be configured. Learn more about this in the package reference.

Package Setup Object

Describes where this package is used in the current hosted account.

Update package

POST https://info-beamer.com/api/v1/package/<package_id>

{
  "Statements": [
    {
      "Action": "package:update:userdata",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

You can only update the userdata object for a package through the API. All other package information can only be updated by syncing the package with its source. See below.

Request parameters

Response

GET https://info-beamer.com/api/v1/package/<package_id>/sync

POST https://info-beamer.com/api/v1/package/<package_id>/sync

{
  "Statements": [
    {
      "Action": "package:update:sync",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This calls supports both GET and POST requests. GET requests make it easier to integrate this API call into any automated post-commit hook. You can use the ?api-key=<...> url argument for authentication in that case.

You cannot edit packages directly on info-beamer hosted. Packages instead are either pulled from a source or synced by git push. For pulled packages you specify the source url when you create a package.

If you want to make changes to a package you'll have to make those at the source and then make info-beamer hosted pull those changes. For git pushed package, using git push will update the package. See git. for more information on how this works and which policy actions you can use in that case.

All setups using the package will automatically be updated if a package is sycned. All devices that use those setups will fetch the changes.

Request parameters

Response

Delete package

DELETE https://info-beamer.com/api/v1/package/<package_id>

{
  "Statements": [
    {
      "Action": "package:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This will delete a package from your account. You cannot delete package that are used in any of your setups. You can find out setups that use a package with the package details API call and look at the .setups[] list.

Playlists

Playlists allow you to organize assets into static or dynamic playlists. Such playlists can then be embedded in other playlists or used in a setup's configuration.

Dynamic playlists can automatically include assets matching various conditions. Every time you update or add a new asset, all dynamic playlists are reevaluated and updated within a few seconds. Updated playlists then instantly trigger updates of other playlists or setups that embed them. This greatly simplifies updating content across different setups.

A playlist at its core consists of slots and filters. Slots are responsible for selecting zero or more assets. Assets can be added directly or can be dynamically added based on conditions like file type or resolution. Once all slots have been evaluated the resulting list of assets can be filtered. Filtering allows you to reorder, trim or otherwise manipulate that list of assets. The result of both slots and filtering produces the final playlist that can be embedded into other playlists or used within your setups.

Create a new playlist

POST https://info-beamer.com/api/v1/playlist/create

{
  "Statements": [
    {
      "Action": "playlist:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request parameters

See the playlist update API call for details on the slots, filters and default_duration parameters.

Response

List playlists

GET https://info-beamer.com/api/v1/playlist/list

{
  "Statements": [
    {
      "Action": "playlist:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Playlist Summary Object

The objecct for each playlist in the playlist list API call has the following elements:

Playlist details

GET https://info-beamer.com/api/v1/playlist/<playlist_id>

{
  "Statements": [
    {
      "Action": "playlist:detail",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request information about a playlist. The playlist_id is expected to be an Integer value.

Response

Playlist uses

An object describing where the playlist is used:

Playlist Slot Object

Each playlist slot is represented by a two element list of ["type", { .. config ..}]. The value of 'type' is a string with one of three possible values while 'config' is an object containing the corresponding configuration depending on the specified type:

Slot type "asset"

An asset slot directly references on of the assets. An asset slot has the following configuration:

Slot type "playlist"

This slot type embeds another playlist within this playlist. Playlists can be nested up to three levels deep. Playlist dependencies cannot by cyclic and you can at most embed 10 other playlists into another playlist.

A slot embedding another playlist has the following configuration:

Slot type "conditions"

This slot type dynamically adds zero or more assets depending on zero or more conditions. A maximum number of 5 condition slots can be added to a single playlist. A single condition slot can have at most 10 conditions. Assets matching all of the provided conditions are added to the playlist. If you want to add assets from mutually exclusive conditions, you'll have to use multiple different 'conditions' slots.

The slot configuration for a 'conditions' slot looks as follows:

Condition Object

Each condition is represented by a two element list of ["type", { .. config ..}]. The value of 'type' is a string representing the type of condition. 'config' is an object containing the corresponding configuration depending on the specified type.

The following conditions are currently supported:

Condition 'orientation'

This condition evaluates each asset's aspect ratio and returns matching assets. This conditions has the following configuration:

The 'vertical' and 'horizontal' values match of the width of an asset exceeds its height or vice versa. The other values only match if the assets is within 0.5% of the specified aspect ratio.

Condition 'resolution'

This condition matches assets with an exact pixel resolution. It has the following configuration:

Condition 'in_path'

This condition matches assets within a single path. A path of an assets is specified by naming-convention, so for example an asset with the filename project A/Outdoor/teaser.jpg will be considered to be in the path project A/Outdoor. Similarly a path value of a/b will match asset with filenames like a/b/image.jpg but not a/image.jpg (as it's not within a/b) or a/b/c/image.jpg (as it is in a/b/c). This condition has the following configuration:

Condition 'filename'

This condition mathes assets based on filename matching. Similar to in_path this will use the naming-convention for determining which part of an assets filename is matched. For an asset with filename of project A/Outdoor/teaser.jpg, this condition will only evaluate the teaser.jpg part (the component after the last /). This condition has the following configuration:

Condition 'group_select'

This condition groups of assets based on a regex. Each group is them emitted in natural order if it contains at least the minimum or exact amount of items. This allows you to select, for example, assets with filenames like, asset-foo-1.jpg, asset-foo-2.jpg, asset-bar-1.jpg, asset-bar-2.jpg and ensure that each group has, in that case, two assets. This condition can be used together with the 'every' filter: The group select can select certain asset groups with an specified size while the 'every' filter then selects the n-th item within each group.

The regex provided requires you to generate two match groups. For the above example something like (.*)-([0-9]+).jpg might work. The first match group selects the asset name while the second group matches the number. Assets are then grouped by name and emitted if the group contains at least two assets.

Condition 'type'

This condition matches on file type (image or video) and optional further restrict the matching assets based on file format. It has the following configuration:

Condition 'tags'

This condition matches any assets tagged with a set of specified tags:

Condition 'userdata'

This condition matches based on each assets userdata. It uses one of five matching function to compare a userdata's top-level value with the condition value.

Conditions are only matched using the following comparison function if the data type within the userdata in compatible. So if you use, for example, "str_eq", any asset with a non-string userdata value will be skipped regardless of how invert is set.

Playlist Filter Object

Each playlist filter is represented by a two element list of ["type", { .. config ..}]. The value of 'type' is a string specifying which filter to apply, while 'config' is an object containing the corresponding configuration depending on the specified type. Filtering works on a list of assets produced by slots and modifies that list. The following filter types are supported:

Filter 'limit'

This filter limits the number of assets in a playlist. It allows you to restrict a playlist to a given number of assets, throwing away any excess asset. This filter has the following configuration:

Filter 'cut'

This filter allows you to restrict a playlist's total play time. There are three different modes to handle assets exceeding the targeted total play time. This filter has the following configuration:

Filter 'clamp_item'

This filter allows you to restrict each individual item's playtime to a minimum or maximum time, specified in seconds. Both limits are optional.

Filter 'dedup'

This filter removes duplicate assets from the playlist. Can be used to remove duplicate assets resulting from different slots adding them. This filter has the following configuration:

Filter 'every'

This filter selects every then n-th asset from each set of set_size assets. As an example: setting n to 1 and set_size to 2 will result in asset 1, 3, 5 and so on. Setting it to n 2 with set_size 2 will result in asset 2, 4, 6 and so on.

Filter 'split'

This filter can split a playlist into multiple parts and then return one of those parts. The main purpose of this filter is to have, for example, two playlists, both embedding a third playlist and then using this filter in both playlists to split them into different parts. This filter has the following configuration:

Filter 'shuffle'

This filter randomizes the order of assets within a playlist. The randomization is stable, so produces the same order if the number of items doesn't change. So playlists won't change every time you save an otherwise unmodified playlist. But you should never rely on the order of a shuffled playlist. This filter doesn't require configuration, so provide an empty configuration object ({}).

Filter 'first_if_any'

This filter's result depend on whether the first slot produces one or more items. If it doesn't produce anything (which can only happen for conditional slots or embedded playlists), all items from the remaining slots get included in the final result. Otherwise, if the first slot produces at least one item, only those will be included in the final result and items from all other slots will be removed.

Filter 'mix'

This filter cycles through all the assets added by each playlist slot and uses a configurable strategy to decide when to switch to the next slot.

The strategy "avoid_touching_slot_idx" tries to arrange items in the produced playlist to avoid items from the same slot to be next to each other in the generated playlist. Obviously that's not always possible if the number of items produced by individual slots differ.

The strategy "equal_slot_playtime" similarly cycles through all items produced by each slot but uses the play time up to this point to make the decision when to switch to the next slot. The result is a playlist that fairly mixes all slots so none dominates the resulting playlist for too long. This also works best if the producing slots contain multiple items and play times of individual items don't differ too much.

See also: slot cycle filter.

Filter 'sort'

Sorts the produced playlist by asset properties.

Filter 'repeat'

Repeats the items produced up to this point multiple times to produce a longer playlist.

"each" to repeat each individual item. |

Note that the resulting playlist cannot exceed 1000 items. Repeating a playlist too often will result in items that exceed this limit being truncated from the generated playlist.

Filter 'orientation'

Filters items from the resulting playlist that don't have the specified orientation.

Filter 'slot_cycle'

Cycles through all slots producing result items. The longest slot determines the length of the produced playlist. For example if you have one slot producing three items, while another slot only produces a single item, that single item will be repeated three times.

Playlist update

POST https://info-beamer.com/api/v1/playlist/<playlist_id>

Request parameters

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "playlist:update:name",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "playlist:update:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

The expected slots value is the same as returned in the playlists playlist details call: It's a list of individual slot objects, each representing either a asset, embedded playlist or a dynamic asset search.

Similarly the filters value corresponds to the returned filters value returned in the playlist details call: It's a list of filters applied to the playlist after generated by all slots. See the filter object documentation for details.

Response

Delete playlist

DELETE https://info-beamer.com/api/v1/playlist/<playlist_id>

{
  "Statements": [
    {
      "Action": "playlist:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This will delete a playlist from your account. You cannot delete playlists that are used in any of your setups or embedded within another playlist. You can find out other objects that use a playlist using the playlist details API call and information returned in its .uses response.

Assets

Assets are files (images, videos, fonts or json data) that can be used to configure your setups.

Upload asset

POST https://info-beamer.com/api/v1/asset/upload

{
  "Statements": [
    {
      "Action": "asset:upload",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

You can upload an asset to your account with this API call. The request is expected to use the multipart/formdata content type.

The following file extensions are supported:

You can overwrite existing asset files by using the filename of an existing asset. Asset filenames are case-insensitive, so TEST.PNG and test.png are treated identically. If you upload an asset with an identical name, the original asset will be replaced and the API call will return the asset id assigned to the previous version. Setups that use such an asset will automatically use the newly uploaded version of the asset. Devices that show this setup will automatically update. If you replace an existing asset, its userdata and tag information will also be overwritten with the new values.

In you're trying to place files into folders, note that the info-beamer backend doesn't know about folders at all. The web dashboard visualizes filenames with / in to create virtual folders. As an example:

If you upload an asset with the filename Testing/Video.mp4, the dashboard will show the file Video.mp4 in the folder Testing. There are no dedicated API calls for folder operations at the moment. All folder operations are based on renaming individual assets.

Request parameters

You must use a application/x-www-form-urlencoded based request for this API call.

Response

Example

Upload the file in $FILE

curl -u :$API_KEY -F file=@$FILE https://info-beamer.com/api/v1/asset/upload

If you want to specify the filename:

curl -u :$API_KEY -F file="@$FILE;filename=folder/example.jpg" https://info-beamer.com/api/v1/asset/upload

Asset Info Object

This is similar to the Setup Asset Info Objects returned in the setup details API call. It provides information about an uploaded asset.

Asset uses

Included in asset info objects returned for individual asset queries like asset details or asset uploads. Describes in detail where the assets is used:

Metadata Object

Information about an asset. Right now the following information is provided:

For images:

For videos:

No metadata information is provided for JSON files or truetype font assets.

Import asset

POST https://info-beamer.com/api/v1/asset/import

{
  "Statements": [
    {
      "Action": "asset:import",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Instead of uploading an asset you can also tell info-beamer hosted to fetch an assets from a publicly reachable url. The importer supports the same asset types and file extensions and the upload asset API. Only HTTP and HTTPS urls are supported.

Request parameters

Response

List assets

GET https://info-beamer.com/api/v1/asset/list

{
  "Statements": [
    {
      "Action": "asset:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Asset details

GET https://info-beamer.com/api/v1/asset/<asset_id>

{
  "Statements": [
    {
      "Action": "asset:detail",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Returns information about an individual asset. The asset_id is expected to be an Integer value.

Response

This call returns an Asset Info Object.

Update asset

POST https://info-beamer.com/api/v1/asset/<asset_id>

You can change certain properties of an uploaded asset with this call.

Request parameters

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "asset:update:userdata",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "asset:update:tags",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "asset:update:filename",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Delete asset

DELETE https://info-beamer.com/api/v1/asset/<asset_id>

{
  "Statements": [
    {
      "Action": "asset:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This will delete the assets. Can asset cannot be deleted if it is used in a setup.

Response

Account

Get account information

GET https://info-beamer.com/api/v1/account

{
  "Statements": [
    {
      "Action": "account:detail",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This will return information about your account.

Response

The quotas returned describe various resources within the account. Right now setups, packages and assets are limited by quotas. Each quota has a current value as well as an optional limit if a limit is in effect. Exceeding the limit will result in failing API calls when creating a new object.

You can also see your current quotas on the account page. The limits can be increased if required. Contact support for that.

Set account information

POST https://info-beamer.com/api/v1/account

Request parameters

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "account:update:default-setup-id",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "device:update:userdata",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Get device connect key

GET https://info-beamer.com/api/v1/account/connect-key

Generate a device connect key. The resulting value can be added to an OS installation as /config/device-connect-key.txt.

Request parameters

{
  "Statements": [
    {
      "Action": "account:connect-key",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Access

Before proceeding, you might take a look at the permission system documentation.

An access describes a relationship between an inviting and an invited account. Here is the flow chart describing the life cycle of an access.

Create access

POST https://info-beamer.com/api/v1/access/create

{
  "Statements": [
    {
      "Action": "access:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Allow access to your account to another user. Alternatively you can create different multiple accesses to your own account using different ACLs.

Request parameters

Response

List access

GET https://info-beamer.com/api/v1/access/list

{
  "Statements": [
    {
      "Action": "access:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Lists all the accesses you created. An access describes a relationship between two info-beamer accounts. This list allows you to see who can access your account. To see which accounts you can access, check out the list shares call.

Response

Access Object

Update access

POST https://info-beamer.com/api/v1/access/<access_id>

Request parameters

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "access:update:description",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "access:update:acl-id",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "access:update:expire",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "access:renew-api-key",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Delete access

DELETE https://info-beamer.com/api/v1/access/<access_id>

Response

Shares

List shares

GET https://info-beamer.com/api/v1/shared/list

{
  "Statements": [
    {
      "Action": "shared:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Lists all the accesses you can use. An access describes a relationship between two info-beamer accounts. This list allows you to see which accounts you have access to. To see which other accounts can access your account, check out the list access call.

Response

Share Object

Join share

POST https://info-beamer.com/api/v1/shared/<access_id>/join

{
  "Statements": [
    {
      "Action": "shared:join",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

If a share isn't joined yet, you can do so using this API call.

Response

Renew API key

POST https://info-beamer.com/api/v1/shared/<access_id>

{
  "Statements": [
    {
      "Action": "shared:renew-api-key",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Renew the API key for a share. This will also immediately invalidate all sessions for the subject's user account. If this call is issued from a session based API key, this one session based API key remains valid.

Request parameters

Response

Leave share

DELETE https://info-beamer.com/api/v1/shared/<access_id>

{
  "Statements": [
    {
      "Action": "shared:leave",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Leaves a share. You'll now longer have access the the shared account. You can also leave an unjoined share. In this case you won't be able to join later.

Response

ACLs

ACLs (access control lists) group policies. You can then use an ACL to control which actions an access is allowed to perform in your account.

Create ACL

POST https://info-beamer.com/api/v1/acl/create

{
  "Statements": [
    {
      "Action": "acl:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request parameters

Response

List ACLs

GET https://info-beamer.com/api/v1/acl/list

{
  "Statements": [
    {
      "Action": "acl:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Lists all the ACL usable by your account.

Response

ACL Object

Update ACL

POST https://info-beamer.com/api/v1/acl/<acl_id>

You can update any ACL that isn't managed.

Request parameters

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "acl:update:name",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "acl:update:policy-ids",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Delete ACL

DELETE https://info-beamer.com/api/v1/acl/<acl_id>

{
  "Statements": [
    {
      "Action": "acl:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

You can only delete an ACL if it's not used in any access. Managed ACLs cannot be deleted.

Response

Policies

Policies are the center of the permission system. They describe which actions are allowed or denied based on certain conditions. info-beamer provides some policies by default but allows you to build your own policies if you want to.

Create Policy

POST https://info-beamer.com/api/v1/policy/create

{
  "Statements": [
    {
      "Action": "policy:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request parameters

Response

List policies

GET https://info-beamer.com/api/v1/policy/list

{
  "Statements": [
    {
      "Action": "policy:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Lists all the policies usable by your account.

Response

Policy Object

Update policy

POST https://info-beamer.com/api/v1/policy/<policy_id>

You can update any policy that isn't managed.

Request parameters

Depending on which request parameters are set, the following policy actions are triggered:

{
  "Statements": [
    {
      "Action": "policy:update:name",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

{
  "Statements": [
    {
      "Action": "policy:update:policy",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Delete policy

DELETE https://info-beamer.com/api/v1/policy/<policy_id>

{
  "Statements": [
    {
      "Action": "policy:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

You can only delete a policy if it's not used in any ACL. Managed policies cannot be deleted.

Response

SSH keys

SSH keys are used to authenticate git pull based package synchronization. An example would be a package within a private repository on github. You can create a custom SSH key on info-beamer.com and specify that as a usable deploy key on github.

Create SSH key

POST https://info-beamer.com/api/v1/ssh/create

{
  "Statements": [
    {
      "Action": "ssh-key:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Request parameters

Response

SSH Key Info Object

This object describes an SSH key used for git pull based package synchronization.

List SSH keys

This call returns all SSH keys created within an account.

GET https://info-beamer.com/api/v1/ssh/list

{
  "Statements": [
    {
      "Action": "ssh-key:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Delete SSH key

DELETE https://info-beamer.com/api/v1/ssh/<ssh_key_id>

{
  "Statements": [
    {
      "Action": "ssh-key:delete",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

This will delete an SSH key. Packages using this SSH key will revert to using the default fallback SSH key shared across all customers.

Response

Sessions

The API keys on the account access page provide long living API keys: They don't expire (at least by default) and if you have access to an API key, no further authentication is required.

Those API keys are great if you want to automated info-beamer hosted from your own backend system. On the other hand, if you want to create your own user web interface and want to log in info-beamer users, API keys can't be used. info-beamer hosted offers the sessions feature for that use case. They can be created by providing either email and password, or can be created directly for any of your accesses. API requests issued by a session have the auth:access:is-session request context variable set to true.

Create session by login

POST https://info-beamer.com/api/v1/session/create/login

This call is no longer supported. Use an OAuth based authentication flow instead.

This API call doesn't require authentication. So you don't need to provide an API key. You have to provide email/password instead.

The total number of concurrent sessions for a single account is limited to 64. Additional sessions will log out the oldest session. This includes dashboard sessions.

This will create a logged in session for an account. The returned API key is essentially a temporary API key for that user. This allows you to create your own frontend where users can log into their info-beamer account. The API key can then be used to issue authenticated requests.

The newly created session API key is bound to the 'main' access of your account. As a result, the returned temporary API key has complete access to the account.

Request parameters

Response

Create session for access

POST https://info-beamer.com/api/v1/session/create/access/<access_id>

{
  "Statements": [
    {
      "Action": "session:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Be sure to properly restrict the access you create sessions for. Otherwise a session might be used to gain elevated privileges. See below.

This API call cannot be called using a session based API key. This prevents a session from creating additional sessions.

The total number of concurrent sessions for a single account is limited to 32. Additional sessions will log out the oldest session. This includes dashboard sessions.

This call allows you to create a new session for any of the defined shares in your account. So you can either create a session for any of your self-accesses or for accounts shared with you by other users.

If you want to allow this session:create action, be sure to prevent the access from using the shared:list call. Otherwise the session can request a list of API keys and can use those to get elevated access to the account.

Response

Create adhoc access

POST https://info-beamer.com/api/v1/adhoc/create

{
  "Statements": [
    {
      "Action": "adhoc:create",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Not strictly a session, but thematically this API call fits in with the other session functions. It allows you to create a temporary API key from an existing API key with a temporary json policy document attached to it that further restricts what the caller can do.

The main use case for this is if you have a server-side app using the info-beamer API and you want to delegate calls like asset/upload to the user's browser. You could in theory do this by setting up a new access with a limited ACL attached to it, but that's complicated and required manual cleanup. Instead you can use this call to create an ephemeral API key with a single additional policy attached to it.

For the use case above you would write a small policy document that only allows uploading to (for example) a single filename or type. You can then submit this policy json document and an expiration time to this API call. You'll get back a new ephemeral API key that is restricted according to the access's permissions (so you can never give out broader access that the key used to call this API) and the provided policy.

It's highly recommended that you use a whitelist based approach for writing policies. The easiest way to do this is to only have Allow statements limited to the exact calls you want to allow. All actions not explicitly allowed will then be denied by default.

Once created, the API key cannot be revoked other than renewing the API key for the access used to call adhoc/create.

The policy document should prevent another call to adhoc:create. Otherwise the adhoc API key can be used to create additional keys forever until the original API key is renewed to deleted.

Request parameters

Response

Session info

GET https://info-beamer.com/api/v1/session

{
  "Statements": [
    {
      "Action": "session:detail",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Provides information about the calling API key.

Response

Destroy session

POST https://info-beamer.com/api/v1/session/destroy

This API call can only be called using a session based API key. You cannot 'destroy' normal API keys using this call. For that, use the access/share APIs.

Invalidates the current session based API key. Use this to log out a users in your own frontend.

Response

Licensing

Certain offline plans as well as using the info-beamer pi standalone player software requires the use of a per-device license. A license is bound to the device's serial number and cannot be released once it as been assigned.

For using license a with info-beamer pi, each license includes a textual license blob that must be saved on the device. That way info-beamer pi can detect it is properly licensed. See info-beamer pi licensing for more information on how that works.

For info-beamer hosted, a new device you add to your account is automatically matched against your licenses using the device's serial. You can check the licensing status by looking at the .offline.licensed value in the device object response returned by both device list and device detail calls.

Assign new license

Licenses must be purchased in the info-beamer shop. They will be added to your account and will initially not be bound to a specific device. If you want to switch over a device of yours to an offline plan or want to run info-beamer pi, you'll have to assign a license to the physical hardware. The device's serial number is used for that. Assigning a license to a device is final and an assigned license cannot be revoked or reused. When automating license assignment, make sure the serial number provided is correct. For manual assignment you can use the License assignment UI on the dashboard.

POST https://info-beamer.com/api/v1/license/create

{
  "Statements": [
    {
      "Action": "license:assign",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

List licenses

This call returns all licenses registered with the account.

GET https://info-beamer.com/api/v1/license/list

{
  "Statements": [
    {
      "Action": "license:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

License Object

List offline plans

This call returns possible offline plans available for a device.

GET https://info-beamer.com/api/v1/offline/list

{
  "Statements": [
    {
      "Action": "offline:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Response

Offline Plan Object

OS

Fetching information about OS releases and generating customized OS versions is fully API automated.

OS release information

GET https://info-beamer.com/api/v1/os/channels

This API call doesn't require authentication

This will return information about available info-beamer OS release channels and their current OS versions.

Response

Channel Info Object

Download Info Object

OS download

GET https://info-beamer.com/api/v1/os/download/<channel>/<filename>

This API call doesn't require authentication

This will redirect towards an url of the requested OS version and format. <channel> is one of the channels returned in the OS release information API. So far it's stable, testing and bleeding.

Two download formats are available with the following filenames:

Response

The response is a 302 redirect towards the downloadable OS installation file.

OS customized download

POST https://info-beamer.com/api/v1/os/customize

{
  "Statements": [
    {
      "Action": "download:customize",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Creates a customized install.zip file or install.img.gz image with additional configuration settings or other added files. This allows you to programmatically create installation files with preset configuration values. This avoids any manual and thus potentially error-prone steps when creating install files and can be, for example, integrated into a custom end user facing dashboard to create branded downloads on demand.

When using the install.zip methods, added files are directly included in the generated zip file.

When using the install.img.gz method, a custom concatenated gzip compressed file is returned. Most imaging programs should be able to support the resulting install.img.gz file. It has been tested with RPI imager. When writing the image to the target storage device, the resulting file system will not yet include the added files. They will get applied once the device boots for the first time and you will see a [*] Applying customizations log output line during bootup and the device will reboot once during initial setup.

Request parameters

Response

Checks

Check calls are meant to be used from automated monitoring systems like nagios or web based monitoring systems like pingdom or uptimerobot. They will return a HTTP status depending on conditions you can set.

The downside of monitoring your devices using this API is that you're implicitly also monitoring info-beamer hosted uptime. This is of course fine but means that your monitoring system will also trigger if info-beamer hosted itself is down or is temporarily returning errors. It's therefore recommended that you don't trigger an error immediately upon detecting a problem but instead try to confirm it using repeated tests. Most services offer this feature.

Never use an API key with full access for calling any of these API calls from your monitoring system as this would allow the monitoring system to completely control everything in your account. Instead create a new limited API key that is restricted to 'check:*' actions.

You can use the Monitoring access ACL for that. Create a new self-access on your permissions page and apply the ACL named Monitoring access. Then use the resulting API key to call the check API.

Devices Check

GET https://info-beamer.com/api/v1/check/devices
HEAD https://info-beamer.com/api/v1/check/devices

{
  "Statements": [
    {
      "Action": "check:devices",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

You can decide which of your devices to check and the conditions that trigger an error. As an example you might filter by location to only include devices with a location name starting with HQ/ and check if any of them has been down for more than 10 minutes using the url parameters:

https://info-beamer.com/api/v1/check/devices?filter:location=HQ/*&check:offline=600

The calls needs to be authenticated. The easiest way is to add an API key to the url by appending &api-key=<THE-API-KEY>. Be sure to read the warning above regarding API key usage.

Request parameters

You need to set at provide at least one of the check: arguments.

Response

Returns a textual response describing the current status. If and only if all filtered devices don't trigger any of the checks, the response is guaranteed to include the string STATUS: OK and will have the HTTP response status 200.

Any error conditions will include the string STATUS: ERROR and return a non-200 HTTP response status. The following error conditions exist at the moment:

• Your filters returned an empty list of devices.
• Any of the filtered devices is either offline or has a maintenance problem. This is detected using the check: arguments.
• Your account balance is negative and your devices are showing a black screen.

A response might look like this:

STATUS: ERROR

Filtering:
  Matching devices: 3/3

Errors:
  Devices with checked errors: 1/3
  Maintenance: 1 devices ids: 28

Misc

List Timezones

GET https://info-beamer.com/api/v1/timezone/list

{
  "Statements": [
    {
      "Action": "timezone:list",
      "Effect": "allow"
    }
  ],
  "Version": 1
}

Requests list of valid timezones.

Response

Userdata

Userdata allows you to assign custom information to a device, setup, package or asset. This information is returned in the list or detail calls. Userdata can be any object. The maximum allows size is 2KB at the moment.

Userdata assigned that way is intended to be used to make your API interactions easier as you can store metadata from your API consuming service.

The userdata stored never ends up on your devices and is only used by the API and permission system.

Thumbnail urls

Various API responses include thumbnail urls. These urls point to a webservice that provides thumbnails for assets/packages and more.

A thumbnail url is valid for as least 30 hours. The response to a thumbnail url request (not the url itself) can be cached indefinitely as it is immutable. This is also reflected in the HTTP response header. Of course if the underlaying resource changes - like the package.png file of a package or the image file for an asset - the thumbnail url changes. In that case the original call for asset/package or setup details will return a different url.

Thumbnails are returned in the PNG format, so they can include transparency from the original asset. By default, returned images are at most 64x64 pixels.

Urls returned from the API don't include url parameters, so you can always append your own parameters starting with a ?. You can specify different dimensions through parameters. You can also use different cropping strategies for a thumbnail. See the following table for all available urls parameters. The thumbnail service can ignore those parameters so you should always enforce the intended size using (for example) CSS rules.

An example thumb url might look like this:

https://cdn.infobeamer.com/<imagepath>?crop=smart&size=100