info-beamer.com hosted API


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.

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 encoded format.

Authentication

Most API calls require authentication. There are two 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 to create new sessions. You'll get a new temporary API key that can issue API calls on behalf of an access.

Regardless of which method you use, you seen your authentication 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 .

Alternatively you can also use the api-key url parameter for authentication.

Rate Limits

While there are no specific rate limits implemented at the moment, 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 if you can use the corresponding /list call.
  • Don't be lazy. A brute force approach might work for a few devices but won't scale. Implement your system properly from the start.

Responses

200 The API call was successful. A JSON object is returned.
400 There was a problem with your API call. You'll get a JSON response with the "error" field containing a textual representation of the error message.
401 Failure to provide a correct API key results in an 401 response.
403 Accessing an object you have no permissios for results in an 403 response.
429 The request has been rate limitied. You should implement an exponentially backoff algorithm to decide when to try the request again.
5xx The API isn't reachable at the moment.

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
Triggers action device:create with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:location String The location of the newly created device.
device:description String The description of the newly created device.
device:setup:id The setup id of the setup assigned by default.

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

pin String The PIN of the device shown on the device welcome screen.
location Optional String The initial device location.
description Optional String The initial device description.
setup_id Optional Integer The id of a setup you want to assign to this device. The new device will immediately start downloading the content and switch to the assigned setup when everything is downloaded.

Response

.device_id Integer A numerical device id that represents the created device.

Example

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

List all devices

GET https://info-beamer.com/api/v1/device/list
Triggers action device:list with the default context variables.

You can match this using the Action value in a policy statement .

List all devices assigned to an account.

Response

.devices[] List of Device Objects.

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:

.id Integer The numerical device id.
.description String The device description as given on the Device page.
.location String The device location as given on the Device page.
.serial String The hardware serial number of the device.
.status String An informal string showing what the device is doing at the moment.
.uuid String The internal unique device UUID. Make sure to keep this ID a secret as it can be used to access all information related to this Pi without further authentication. It still doesn't allow access to your account but someone with access to this ID can fetch all current and future files assigned to this device from the info-beamer storage service, just like the device itself does.
.is_online Boolean true if the device is online and has recently contacted the info-beamer hosted service.
.is_synced Boolean/Null Is the device in sync with what is configured on info-beamer hosted?
.maintenance[] List of Strings If the device needs maintenance the problem is marked here. See Maintenance flags.
.run Run Object Information about the current boot up cycle. This information is gathered when the device contacts the info-beamer hosted service. If there has not been any recent contact, this object might be empty.
.userdata Object User supplied data assigned to this device. You can store any data for a device here.
.reboot Integer The maintenance hour given in an offset from 0:00 in UTC time. The device might reboot in this hour if there is an important update.
.setup Object/Null If non-null, it contains information about the running setup. If there is no setup installed yet, this value is null.
.geo Object/Null Geolocation information about this device. Can be null if the device hasn't been seen online yet or a device location isn't available.
.geo.lat Float Specifies the device latitude if a geolocation is available.
.geo.lon Float Specifies the device longitude if a geolocation is available.
.geo.source String Specifies how the geolocation is generated. Can be either "wifi" if it's based on nearby WiFi networks or "ip" if it's based on the device last known public ip address. See also the device location call.
.setup Object/Null Information about the assigned setup or null if no setup has been assigned yet.
.setup.id Integer The id of the installed setup.
.setup.name String The name of the installed setup.
.setup.updated Integer Unix timestamp of when the setup was last changed. Changes include name changes, changing the configuration or setting new userdata.
.hw Optional object Information about this hardware
.hw.type String Hardware type, always 'pi' at the moment.
.hw.model String Model name
.hw.memory String Memory in MB
.hw.platform String Platform code
.hw.features List of Strings Lists the supported features.

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.

"sd-card" There is some problem with the SD card (like corruption/removal)
"network" A network problem has been detected. Loss of connection, etc...
"power-adapter" There is a power problem. The attached power adapter might not provide enough power.
"temperature" Temperature problem. The device got too hot and was throttled.

Run Object

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

.channel String The current active release channel.
.public_addr String The public IP address of the device.
.resolution String A textural representation of the screen resolution active when the device started.
.restarted Integer The unix timestamp of the last device reboot.
.tag String The major release version of the running operating system. Sortable.
.version String The exact version of the running operating system. Sortable within its channel.
.boot_version String The exact version of the running operating system. Sortable within its channel. Obsolete: use 'version' instead.
.base_version String The exact version of the running operating system. Sortable within its channel. Obsolete: use 'version' instead.
.pi_revision String The hardware revision of the Pi.

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>
Triggers action device:detail with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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
Triggers action device:detail:telemetry with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

Response

.telemetry An object of multiple list values
.telemetry.timestamps[] A list of Integers (unix timestamps) for each sample taken.
.telemetry.fps[] A list of Floats with the measured frame rate at the sample point.
.telemetry.load[] A list of Floats with the measured system load at the sample point.
.telemetry.mem[] A list of Integers with the measured memory usage of the running visualization at the sample point.
.telemetry.temp[] A list of Floats with the measured CPU temperature of the Raspberry Pi.

Device snapshot

GET https://info-beamer.com/api/v1/device/<device_id>/output
Triggers action device:detail:output with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

.width The screenshot width in pixels.
.height The screenshot height in pixels.
.src An url where the screenshot can be retrieved. The image will be provided in the JPEG format. Right now a data url is returned. In the future a temporary url might be returned instead. The given url will be valid for at most 5 minutes.

Device sensor info

GET https://info-beamer.com/api/v1/device/<device_id>/sensor
Triggers action device:detail:sensor with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

.cpu Object CPU information.
.cpu.idle Float Current Idle %
.disk Object Disk information.
.disk.available Integer Available SD space in KB.
.disk.used Integer Used disk space in KB.
.disk.io.read Integer Total number of read bytes.
.disk.io.write Integer Total number of written bytes.
.disk.manfid String Manufacturer ID of the SD card.
.disk.oemid String OEM/Application ID of the SD card.
.info_beamer Object Information about the running info-beamer process
.info_beamer.fps Float Current FPS
.info_beamer.uptime Integer Current uptime of the info-beamer process
.info_beamer.version String Currently running version of info-beamer pi
.net Object Information about the network connection.
.net.data.received Integer Number of bytes received.
.net.data.sent Integer Number of bytes sent.
.net.dev String Either "wlan0" or "eth0" depending on whether wireless of an ethernet connection is used.
.net.ip String Local IP address assigned to the device.
.net.mac String MAC address of the network device.
.pi Object Information about the Pi/firmware.
.pi.gpu Integer Available GPU memory.
.pi.arm Integer Available ARM/Linux memory.
.pi.revision String The Pi hardware revision.
.pi.version String The Pi firmware version.
.p2p.enabled Boolean True if peer-to-peer is enabled.
.p2p.peers Integer Number of detected peers (including this device)
.p2p.time_spread Float Maximum time difference between all devices. A value of 0 means that all devices are in perfect sync. The lower the value the better.
.p2p.traffic.cdn Integer Number of bytes downloaded from the info-beamer storage servers.
.p2p.traffic.p2p Integer Number of bytes downloaded from other p2p enabled devices.
.services.<service> Object Information about a service running on your device. package services always start with service followed by a dotted version of their node path. An example would be service.root for the package service of the top level node of the running setup. Installing a new version of a package service resets all its values.
.services.<service>.io_read Integer Number of bytes read by this service.
.services.<service>.io_write Integer Number of bytes written by this service.
.services.<service>.mem_cache Integer Cached memory used by this service.
.services.<service>.mem_rss Integer Memory (resident set size) used by this service.
.ssh Object Information about the optionally running SSH daemon.
.ssh.fingerprint Optional String If SSH is running this will contain the SSH public key in hex notation. Either MD5 or SHA1 fingerprint values will be returned.
.temp Float The Pi CPU temperature.
.uptime Integer Device uptime in seconds.
.updater Object Information about system updates.
.updater.updated Boolean Is system update available and the device is ready for a reboot to activate it?
.updater.version Optional String If update is ready. Which version are we going to reboot into?
.updater.channel Optional String If update is ready. Which channel are we going to reboot into?
.video Object Information about current video mode
.video.device String Name of connected display detected using EDID
.video.hz String Refresh rate
.video.resolution String Output resolution
.video_secondary Optional Object Information about current video mode for a secondary display. See .video for values

Device reboot

POST https://info-beamer.com/api/v1/device/<device_id>/reboot
Triggers action device:reboot with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

Response

.ok true The request was successful and then device is going to reboot.

Device location

GET https://info-beamer.com/api/v1/device/<device_id>/location
Triggers action device:location:update with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

.lat Float Device latitude.
.lon Float Device longitude.
.address String Automatically detected address.
DELETE https://info-beamer.com/api/v1/device/<device_id>/location
Triggers action device:location:delete with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

Response

.ok true The request was successful. Existing lat and lon values stored have been removed.

Device config

GET https://info-beamer.com/api/v1/device/<device_id>/config
Triggers action device:config:read with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

.<filename> String base64 encoded content of <filename>
POST https://info-beamer.com/api/v1/device/<device_id>/config
Triggers action device:config:write with 6 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
config:set:<filename> Boolean Set in the context (always to true) if <filename> will be added to the device. Currently the dashboard editor will always set all active config values regardless of whether they are newly changed or already had the value set. So you cannot match a UI action that only tries to change a single value.
config:delete:<filename> Boolean Set in the context (always to true) if <filename> will be removed from the device. See the note above for limitation regarding the current UI editor.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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. The device will then reboot.

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 into the previous version. This will reverse all configuration changes made but ensures a device is usable even if an invalid configuration was applied.

Request parameters

config JSON Object The new configuration. Keys within the given JSON object are filenames of files to place in the /config directory on the device. The value is either null if you want to remove an existing file or the base64 encoded value of the new file content. The maximum size of each config value is 8K.

Response

.ok true The request was successful and the device will apply the new configuration.

Device command

POST https://info-beamer.com/api/v1/device/<device_id>/node/<path>
Triggers action device:node-message with 6 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
message:path String The target node path.
message:data String The sent message.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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.

data String The string sent to the node

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

.ok true The request was successful.

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 session

POST https://info-beamer.com/api/v1/device/<device_id>/session
Triggers action device:session with 5 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
session:mode String The mode (see below) of the session created.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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).

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

mode Optional String Either viewer or root. Defaults to viewer. In viewer mode, the shell is restricted and doesn't have access to the network or the complete filesystem. This mode is intended mostly for debugging purposes and is mostly safe. In root mode you get a full root shell which allows unrestricted access to the device and is quite dangerous as you can break a device in a way that requires a new installation.

Response

.session_id String The generated session id.
.mode String The selected terminal mode.
.endpoint String The url to a websocket endpoint that connects you to the device.

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.

Request parameters

userdata Optional JSON Object A JSON object with opaque user data of your choice. Maximum size is 2k.
location Optional String The new device location.
description Optional String The new device description.
setup_id Optional Integer The id of a setup you want to assign to this device. Once assigned the device will immediately start downloading the content and switch to the assigned setup when everything is downloaded.
reboot Optional Integer A value from 0-23 inclusive which sets the maintenance hour given in hours since 0:00 UTC time. The device might reboot in that hour for maintenance tasks.
mark_fixed Optional 1 If provided this will reset the maintenance flags.

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

Triggers action device:update:userdata with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action device:update:location with 5 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
update:location String The new location value.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action device:update:description with 5 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
update:description String The new description value.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action device:update:reboot with 5 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
update:reboot Numeric The new reboot value.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action device:update:mark-fixed with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action device:update:setup with 6 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
update:setup:id Numeric The id of the newly assigned setup.
update:setup:name Numeric The name of the newly assigned setup.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

You can only assign new setups to a device. You cannot make a device show no setup once you've assigned one. If you need to show a black screen, you'll have to create a setup that does just that and assign it.

Response

.ok true The request was successful and all requested changes have been made.

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&name=My%20Pi

Delete device

DELETE https://info-beamer.com/api/v1/device/<device_id>
Triggers action device:delete with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
device:id Numeric The device id.
device:location String The current location value.
device:description String The current description value.
device:serial String The device serial.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

.ok true The request was successful. The device will clean its cache and reboot at the next possible moment. The device will then return to the device welcome screen.

Example

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

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
Triggers action package:create with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
package:source String The url source. Set to null is this is a new pushable package.
package:asset-check Boolean True if asset_check is set.
package:origin String Indicates where the package comes from. Set to "url" if the package is imported from a remote url. Set to "git" for a git pushable package. Set to "store" if the package is created from the info-beamer solution store.

Request parameters

source Optional String The source url for the package. See below.
asset_check Optional String Decides if the import should apply additional checks during import and syncs. See below.
userdata Optional Object User supplied data assigned to this package. You can store any data for a package here.

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

.package_id Integer A numerical device id that represents the created package.

List all packages

GET https://info-beamer.com/api/v1/package/list
Triggers action package:list with the default context variables.

You can match this using the Action value in a policy statement .

Response

.packages[] List of Package Objects

Package Object

The objecct for Each package in the package list API call has the following elements:

.id Integer The package id.
.size Integer The toal package size in bytes. This is used for generating the daily costs and can also be used to estimate the number of byte required to send a package to a device.
.used Integer A counter indicating how often this package is used as an instance in a setup. Packages cannot be deleted if they are still in use.
.pushed Boolean Is the package git pushed?
.public_url Optional String If this is a public package, this will contain the url to its public page.
.info Package Info Object Detailed information about this package.
.available_update Optional Package Version Object Information about an available upgrade for this package.
.userdata Object User supplied data assigned to this package. You can store any data for a package here.

Package details

GET https://info-beamer.com/api/v1/package/<package_id>
Triggers action package:list with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
package:id Numeric The package id
package:source String The package source or null in casse of a git pushed package.

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

Response

.id Integer The package id
.info Package Info Object Information about this package
.last_sync Integer Unix timestamp of the time the package was last synced with its source.
.size Integer The complete size of the package in bytes.
.asset_check Boolean Whether info-beamer hosted does additional asset checks on all files in this package. See the asset_check option while creating a package.
.userdata Object User supplied data assigned to this package. You can store any data for a package here.
.pushed Boolean Is the package git pushed?
.source String/Null The url from which the package was initially imported. If it's a git pushed package, the source is null.
.version String/Null The "version" of the source. For git repositories this is the branch that was imported.
.git_push_url Optional String If this is a git pushed repository, this is the https endpoint used as a git remote.
.available_update Optional Package Version Object Information about an available upgrade for this package.
.release Optional Package Version Object If the package has a current version (in .info.version), this will contain additional information about the current version.
.public_url Optional String If this is a public package, this will contain the url to its public page.
.files[] List of Package File Objects Describes the individual files within that package.
.nodes[] List of Package Node Objects Describes the info-beamer nodes in this package.
.presets[] Object All available predefined configuration values for this package. They are defined within each node.json file of this package. The key can be used as the preset value in the create setup API call.
.setups[] List of Package Setup Objects Describes in which setups this package is used.
.docs.help String Raw HTML for the documentation page of the package. This HTML can be directly used to render the documentation of a package. It's based on the README.md or README.creole file. If no documentation is included in the package, an empty string is returned.
.doc.copyright String Raw HTML for the copyright page of the package. It's based on the COPYRIGHT file. If no such file is included in the package, an empty string is returned.

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.

.version String The new/current version number.
.changelog String An url to the changelog of the new/current version.

Package File Object

Gives information about an individual files in a package.

.path String The complete filename including path of the file.
.size Integer Size in bytes.
.hash String The md5 hash of the file. This is used internally.

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.

.name String The name of that node. This is taken from the node.json file of the node.
.path String The path of the node within the package. The empty string "" denotes that this is the root node within the package.
.has_service Boolean Indicates if this node includes a package service.
.permissions Object Permissions. See node permissions for possible values.
.thumb String A thumbnail url that can be used to represent this node.

Package Setup Object

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

.id Integer The id of the setup that uses this package.
.name String The name of the setup that uses this package.
.instance_id Integer The instance id of this package.
.path String Where within the referenced setup is this package attached? The empty string (""), for example, means that this package the root package of the referenced setup.
.used Integer A counter indicating the number of devices the setup is assigned to.

Update package

POST https://info-beamer.com/api/v1/package/<package_id>
Triggers action package:update:userdata with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
package:id Numeric The package id
package:source String The package source or null in casse of a git pushed package.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

userdata Optional Object User supplied data assigned to this package. You can store any data for a package here.

Response

.ok true Userdata was updated.
GET https://info-beamer.com/api/v1/package/<package_id>/sync
POST https://info-beamer.com/api/v1/package/<package_id>/sync
Triggers action package:update:sync with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
package:id Numeric The package id
package:source String The package source or null in casse of a git pushed package.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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.

Response

.ok true The source for that package was successfully contacted. The package is now in sync with the source.
.updated Integer Number of updated files (added/changed/removed).

Delete package

DELETE https://info-beamer.com/api/v1/package/<package_id>
Triggers action package:delete with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
package:id Numeric The package id
package:source String The package source or null in casse of a git pushed package.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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.

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 with the Instance API. 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
Triggers action setup:create with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
package:id Numeric The package id of the setup root package.
setup:name String The name of the new setup.

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

Request parameters

package_id Integer The id of the package at the root of the package tree. See above for more information about this.
name String The name of the setup.
userdata Optional Object User supplied data assigned to this setup. You can store any data for a setup here.
preset Optional String Name of a preset. The valid values for creating a setup based on a setup can be found in the .presets object of the package details API call.

Response

.setup_id Integer A numerical id that represents the created setup.

List all setups

GET https://info-beamer.com/api/v1/setup/list
Triggers action setup:list with the default context variables.

You can match this using the Action value in a policy statement .

Lists all setups in an account.

Response

.setups[] A list of Setup Info Objects

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:

.id Integer The id of the setup
.name String The name assigned to this setup. You can change the name with the Setup update API call.
.used Integer A counter indicating the number of devices this setup is assigned to.
.userdata Object User supplied data assigned to this setup. You can store any data for a setup here.
.updated Integer Unix timestamp of when the setup was last changed. Changes include name changes, changing the configuration or setting new userdata.
.is_default Boolean If true, this setup is automatically assigned to new devices. Only one setup can have a true value.
.platforms List of strings List of platforms compatible with this setup. It's the intersection of platform compatibility of all used packages.
.has_expands Optional Boolean If available, indicates if the setup configuration is a result of expanding.

Setup details

GET https://info-beamer.com/api/v1/setup/<setup_id>
Triggers action setup:detail with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
setup:id Numeric The setup id.
setup:name String The name of the setup.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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 Object An object describing the setup. This is basically a Setup Info Object.
.assets Object A description of assets included in each node in the setup. Each individual object key is a complete node path. The values are a list of Setup Asset Info Objects.
.config Object The current configuration for each node in the setup. The keys of the object are the complete node paths with the leading / removed. Each individual value is the the current node configuration as another Object. The content of that objects depends on the configuration options for each node.
.instances Object All packages assigned to this setup. The object's keys are the path within the setup. The value is an Setup Instance Object.
.nodes Object Information about all nodes includes through all packages. The object's keys are the node paths within the setup. The values is an Setup Node Object.
.presets Object Available predefined configuration examples for this setup. It's a combination of all the node preset values defined in the node.json file. The "config" value within each preset in this object can be directly used as a config parameter for the update setup API call.

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.

.id Integer The instance id
.parent_id Integer/Null The id of the parent instance. null will be returned if this instance is the top level instance within this setup.
.package Object A description of the package of this instance.
.package.id Integer The package id.
.package.info Package Info Object Information about this package.
.package.last_sync Integer Unix timestamp of the time the package was last synced with its source.

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:

.author String A free text value describing the author of the package
.name String The package name.
.desc String A short description of the package.
.image String A thumbnail url for a small 64x64 image of the package.
.repository String/Null A http/https url linking to the package source repository.
.version String/Null The free form package version number given in package.json
.lifecycle String The current lifecycle of this package. Values are "alpha", "beta", "production" and "obsoleted"
.platforms List of strings A list of supported platforms.

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.

.name String Name of the node. This is the name given in node.json.
.instance_id Integer The id of the package instance that provided this node. See the id field in the setup instance object.
.num_expands Integer How many configuration options have been created through expands.
.custom_ui String/Null If the node has a custom user HTML interface for its configuration, the filename of that interface is returned here. This is mostly for internal use.
.control_ui String/Null If the node has a custom control HTML interface, the filename of that interface is returned here. This is mostly for internal use.
.options[] List of Objects Zero or more options describing the configuration options available for this node. You can see a complete description for all options in the package reference.
.has_service Boolean Indicates if this node includes a package service.
.permissions Object Permissions. See node permissions for possible values.
.thumb String A thumbnail url that can be used to represent this node.

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:

.id String The id of the asset used when configuring this node. Unlike user uploaded assets, where the id is numeric, the id for node specific assets is given as a string. The string is unique in the scope of each node.
.filename String The filename of the asset
.filetype String Type of asset. Can be "image", "video", "font", "json" or "child".
.size Integer The file size of the asset.
.thumb String A thumbnail url of the asset.

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

userdata Optional JSON Object A JSON object with opaque user data of your choice. Maximum size is 2k. The userdata is returned in the Setup Info Object.
name Optional String The new name of this setup.
config Optional Object The new configuration for this setup. See the following description.
mode Optional String If a new config is provided, this decides how this config is merged with the existig config.

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

Triggers action setup:update:userdata with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
setup:id Numeric The setup id.
setup:name String The name of the setup.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action setup:update:config with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
setup:id Numeric The setup id.
setup:name String The name of the setup.
update:mode String The configuration update mode.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action setup:update:name with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
setup:id Numeric The setup id.
setup:name String The name of the setup.
update:name String The new setup name.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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.

Attach package instance

POST https://info-beamer.com/api/v1/instance/create
Triggers action instance:create with 8 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
setup:id Numeric The setup id of the modified setup.
setup:name String The name of the modified setup.
package:id Numeric The package id of the newly attached package instance.
package:source Numeric The source of the newly attached instance.
parent:package:id Numeric The package id of the parent package within the setup.
parent:package:source Numeric The source of the parent package.
instance:path String The base path where the instance is attached.
instance:name String The name of the new instance.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

instance_id Integer The id of the package instance where you want to attach a new instance. You can get this id in the Setup instance object.
package_id Integer The id of the package you want to add. You can get this id in the Packages list API call.
name String The name of the package. Only lowercase alphanumeric characters (a-z / 0-9 or _ / - can be used. Cannot contains spaces or be empty.

Response

.instance_id Integer A numerical id that represents the newly created instance. It has been attached to the given instance.

Delete package instance

DELETE https://info-beamer.com/api/v1/instance/<instance_id>
Triggers action instance:delete with 5 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
setup:id Numeric The setup id of the modified setup.
setup:name String The name of the modified setup.
instance:id String The instance id to be removed.
instance:path String The base path from where the instance and its childs are removed.
instance:name String The name of the removed instance.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

.ok true The request was successful. The instance and its childs have been removed from their setup.

Delete setup

DELETE https://info-beamer.com/api/v1/setup/<setup_id>
Triggers action setup:delete with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
setup:id Numeric The setup id of the setup to be deleted.
setup:name String The name of the setup.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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.

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
Triggers action asset:upload with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
asset:filename String Filename of the newly uploaded asset.
asset:filetype String The filetype of the uploaded asset. Can be 'video', 'image', 'font' or 'json'.
asset:exists Boolean True of the upload will overwrite an existing asset.
asset:metadata:<key> String The value of the detected metadata for <key>.

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:

mp4, mov, mkv Video files. Must be in h264 format.
jpg, png Image files. The image must not be bigger than 2048x2048 pixels.
ttf, otf Font files.
json JSON data file.

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.

Request parameters

file Binary The binary file content.
tags Optional String A comma separated string with tags that will be assigned to the asset.
userdata Optional JSON Object User supplied data assigned to this asset. Must be JSON formatted. Up to 2k can be stored.

Response

.ok true The file was uploaded and imported into the account.
.asset_id Integer The asset id of the uploaded file.
.info Asset Info Object Information about the uploaded asset.

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.

.id Integer The id of the asset. This is a numeric if, unlike the asset ids returned in the setup details API call, which are always strings.
.features List of Strings Lists the required features to play this asset on a device.
.filename String The filename of the asset
.filetype String Type of asset. Can be "image", "video", "font", "json" or "child".
.size Integer The file size of the asset.
.thumb String A thumbnail url of the asset.
.metadata Metadata Object Metadata about the asset.
.userdata Object A JSON object with opaque user data.
.used Integer A counter indicating how often this asset is used in your setups. Assets cannot be deleted (only overwritten) if they are still in use.
.uploaded Integer Unix timestamp of when the asset was uploaded.
.tags[] List of Strings Tags assigned to this asset during the upload.
.json Optional Object If the asset is a json file, its content will be returned.

Metadata Object

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

For images:

.width Integer Image width.
.height Integer Image height.
.format String The image file format: "PNG" or "JPEG".

For videos:

.width Integer Video width.
.height Integer Video height.
.format String Video format. Always "h264" at the moment.
.duration Float Video duration in seconds.

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

Example

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

Import asset

POST https://info-beamer.com/api/v1/asset/import
Triggers action asset:import with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
asset:filename String Filename of the newly uploaded asset.
asset:filetype String The filetype of the uploaded asset. Can be 'video', 'image', 'font' or 'json'.
asset:exists Boolean True of the upload will overwrite an existing asset.
asset:metadata:<key> String The value of the detected metadata for <key>.

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

url String The HTTP(S) url of the asset to be imported.
filename Optional String The filename of the imported asset. If no filename is given the filename from the url parameter will be used
tags Optional String A comma separated string with tags that will be assigned to the asset.
userdata Optional JSON Object User supplied data assigned to this asset. Must be JSON formatted. Up to 2k can be stored.

Response

.ok true The file was uploaded and imported into the account.
.asset_id Integer The asset id of the uploaded file.
.info Asset Info Object Information about the uploaded asset.

List all assets

GET https://info-beamer.com/api/v1/asset/list
Triggers action asset:list with the default context variables.

You can match this using the Action value in a policy statement .

Response

.assets List of Asset Info Objects All assets.

Asset details

GET https://info-beamer.com/api/v1/asset/<asset_id>
Triggers action asset:detail with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
asset:id Numeric The asset id.
asset:filename String The filename of the asset.
asset:filetype String The filetype of the asset.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

userdata Optional JSON Object Custom data assigned to this asset. Must be JSON formatted. Up to 2k can be stored.
tags Optional String A comma separated string with tags that will be assigned to the asset.
filename Optional String Updates the filename of the stored asset. The new name must not already exist in the account. So you can't overwrite existing assets that way.

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

Triggers action asset:update:userdata with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
asset:id Numeric The asset id.
asset:filename String The filename of the asset.
asset:filetype String The filetype of the asset.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action asset:update:tags with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
asset:id Numeric The asset id.
asset:filename String The filename of the asset.
asset:filetype String The filetype of the asset.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.
Triggers action asset:update:filename with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
asset:id Numeric The asset id.
asset:filename String The filename of the asset.
asset:filetype String The filetype of the asset.
update:filename String The new filename.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

Response

.ok true The request was successful. The assets properties have been updated.

Delete asset

DELETE https://info-beamer.com/api/v1/asset/<asset_id>
Triggers action asset:delete with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
asset:id Numeric The asset id.
asset:filename String The filename of the asset.
asset:filetype String The filetype of the asset.
userdata:<key> variable types Value of the associated userdata. See userdata context values for more information.

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

Response

.ok true The request was successful. The assets has been deleted.

Account

Get account information

GET https://info-beamer.com/api/v1/account
Triggers action account:detail with the default context variables.

You can match this using the Action value in a policy statement .

This will return information about your account.

Response

.balance Float The current account balance.
.default_setup_id Integer/Null The id of the default setup that is assigned to new devices
.devices_active Boolean Whether your devices show their content. false usually means that your account balance is negative.
.email String The email address associated with your account.
.usage.devices Integer Number of active devices.
.usage.storage Integer Used storage in bytes.

Set account information

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

Right now the only account wide action is to set a new default setup that is installed on new devices.

Request parameters

default_setup_id Integer/Emtpy The id of the default setup that is installed for new devices. If you send an empty string the default setup feature is disabled and you'll have to manually assign setups to new devices.

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

Triggers action account:update:default-setup-id with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
update:setup:id Numeric The id of the new default setup.
update:setup:name String The name of the new default setup.

Response

.ok true The request was successful and then setting was applied.

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
Triggers action access:create with 4 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
access:subject:email String The email of the accessing user for the newly created access.
access:object:email String The email of the accessed user.
access:description String The access description.
access:expire Numeric Number of seconds in the future when the access will expire.

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

Request parameters

email Optional String Email address of the invited users. Can be left empty to create a new access to your own account.
acl_id Integer References an access control list controlling this access.
description String A description that helps you remember why this access exists.
expire Optional Integer A unix timestamp marking the expiration date of this access. If absent or set to 0, the access will not expire.

Response

.ok true The request was successful.
.access_id Integer The access id created. If you left email empty, you'll have a new share with a new API key. If you invited another user, they'll have to join the access before they can use it.

List access

GET https://info-beamer.com/api/v1/access/list
Triggers action access:list with the default context variables.

You can match this using the Action value in a policy statement .

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[] A list of Access Objects

Access Object

.id Integer The access id
.accessor.email String Email address of accessing account.
.accessor.is_you Boolean If this access is for your own account.
.accessor.icon String Url to a thumbnail of the accessing account. 64x64 pixels.
.acl.id Integer The ACL effective for this access.
.acl.name String Name of the ACL.
.created Integer Unix timestamp of when the access was created.
.joined Integer/Null Unix timestamp of when the invited account joined this access. If null, the invited user hasn't joined yet.
.expires Integer/Null Unix timestamp when the access expires. If null, this access does not expire.
.is_expired Boolean If the access is expired.
.description String Description provided when creating this access.
.managed Boolean System managed access?

Update access

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

Request parameters

description Optional String A new description.
acl_id Optional Integer If provided, updates the ACL used by this access.
expire Optional Integer If provided, the Unix timestamp sets a new expiration time. Use 0 to remove the expiration.

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

Triggers action access:update:description with 6 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
access:id Numeric The changed access id.
access:subject:email String The email of the accessing user.
access:object:email String The email of the accessed user.
access:description String The access description
access:expire-at Integer The unix timestamp of when the access expires.
update:description String The new description.
Triggers action access:update:acl-id with 6 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
access:id Numeric The changed access id.
access:subject:email String The email of the accessing user.
access:object:email String The email of the accessed user.
access:description String The access description
access:expire-at Integer The unix timestamp of when the access expires.
update:acl:id Numeric The id of the new ACL.
Triggers action access:update:expire with 6 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
access:id Numeric The changed access id.
access:subject:email String The email of the accessing user.
access:object:email String The email of the accessed user.
access:description String The access description
access:expire-at Integer The unix timestamp of when the access expires.
update:expire Numeric Number of seconds in the future when the access will now expire.

Response

.ok true The request was successful. The access has been updated and is immediately effective.

Delete access

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

Response

.ok true The request was successful. The access has been removed and access to your account using this access is immediately prevented.

Shares

List shares

GET https://info-beamer.com/api/v1/shared/list
Triggers action shared:list with the default context variables.

You can match this using the Action value in a policy statement .

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

.shared[] A list of Share Objects

Share Object

.id Integer The access id
.sharer.email String Email address of sharing account.
.sharer.is_you Boolean If this share is for your own account.
.sharer.icon String Url to a thumbnail of the sharing account. 64x64 pixels.
.api_key String API key for using accessing the shared account.
.created Integer Unix timestamp of when the access was created.
.joined Integer/Null Unix timestamp of when you joined this access. If null, you haven't joined yet.
.expires Integer/Null Unix timestamp when the access expires. If null, this access does not expire.
.is_expired Boolean If the access is expired.
.description String/Null Description provided when creating this access. This value is null for all shares for other accounts (so if sharer.is_you == false)
.can_leave Boolean Can you leave this share?

Join share

POST https://info-beamer.com/api/v1/shared/<access_id>/join
Triggers action shared:join with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
access:id Numeric The changed access id.
access:subject:email String The email of the accessing user.
access:object:email String The email of the accessed user.

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

Response

.ok true The request was successful. You can now access this account through the dashboard or using the API key returned in the list shares call.

Leave share

DELETE https://info-beamer.com/api/v1/shared/<access_id>
Triggers action shared:leave with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
access:id Numeric The changed access id.
access:subject:email String The email of the accessing user.
access:object:email String The email of the accessed user.

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

.ok true The request was successful. The associated API key for this share is no longer valid and you cannot access the shared account.

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
Triggers action acl:create with 1 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
acl:name String The name of the new ACL.

Request parameters

name String ACL name.
policy_idsString Comma separated list of policy_ids.

Response

.ok true The request was successful.
.acl_id Integer The id of the newly created ACL.

List ACLs

GET https://info-beamer.com/api/v1/acl/list
Triggers action acl:list with the default context variables.

You can match this using the Action value in a policy statement .

Lists all the ACL usable by your account.

Response

.acls[] A list of ACL Objects

ACL Object

.id Integer The ACL id
.managed Boolean If this is a managed ACL. Managed ACLs cannot be edited or deleted.
.created Integer Unix timestamp of when the ACL was created.
.description String Name of the ACL.
.policy_ids[] List of Integers Assigned policies.
.used Integer How often this policy is used in in your accesses.

Update ACL

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

You can update any ACL that isn't managed.

Request parameters

name Optional String A new name.
policy_ids Optional String If provided, updates the assigned policies. The values must be a list of comma separated policy_ids.

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

Triggers action acl:update:name with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
acl:id Numeric The id of the modified ACL.
acl:name String The name of the modified ACL.
update:name String The new name of the ACL.
Triggers action acl:update:policy-ids with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
acl:id Numeric The id of the modified ACL.
acl:name String The name of the modified ACL.

Response

.ok true The request was successful. The ACL has been updated and is immediately effective.

Delete ACL

DELETE https://info-beamer.com/api/v1/acl/<acl_id>
Triggers action acl:delete with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
acl:id Numeric The id of the deleted ACL.
acl:name String The name of the deleted ACL.

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

Response

.ok true The request was successful. The ACL has been deleted.

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
Triggers action policy:create with 1 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
policy:name String The name of the new policy.

Request parameters

name String Name of the new policy.
policy JSON The json policy document.

Response

.ok true The request was successful.
.policy_id Integer The policy id created.

List policies

GET https://info-beamer.com/api/v1/policy/list
Triggers action policy:list with the default context variables.

You can match this using the Action value in a policy statement .

Lists all the policies usable by your account.

Response

.policies[] A list of Policy Objects

Policy Object

.id Integer The policy id
.managed Boolean If this is a managed policy. Managed policies cannot be edited or deleted.
.created Integer Unix timestamp of when the policy was created.
.name String Name of the policy.
.policy Object The policy document.
.used Integer How often this policy is used in in your ACLs.

Update policy

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

You can update any policy that isn't managed.

Request parameters

name Optional String If provided, a new policy name.
policy Optional JSON If provided, a new json policy document.

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

Triggers action policy:update:name with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
policy:id Numeric The id of the modified policy.
policy:name String The name of the modified policy.
update:name String The new name of the policy.
Triggers action policy:update:policy with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
policy:id Numeric The id of the modified policy.
policy:name String The name of the modified policy.

Response

.ok true The request was successful. The policy has been updated and is immediately effective.

Delete policy

DELETE https://info-beamer.com/api/v1/policy/<policy_id>
Triggers action policy:delete with 2 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
policy:id Numeric The id of the modified policy.
policy:name String The name of the modified policy.

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

Response

.ok true The request was successful. The policy has been deleted.

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.

Right now, the API only allows CORS requests from a handful of domains. If you want to use this feature, get in contact with support and we can quickly enable CORS for your domain. 'localhost' is always allowed, so you can test with a locally running interface without getting in contact.

Create session by login

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

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 32. 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

email String Account email address.
password String Account password.

Response

.api_key String A temporary API key with full access to the given account.

Create session for access

POST https://info-beamer.com/api/v1/session/create/access/<access_id>
Triggers action session:create with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
session:access:id Numeric The access if requested for the new session.
session:access:description String The access description
session:for-this-access Boolean This session API call needs to be authentication by any of your own API keys. So it's scoped to an access. This boolean indicates if the requested session will have the same access as the one issuing this API call.

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

.api_key String A temporary API key with access according to the given share.

Session info

GET https://info-beamer.com/api/v1/session
Triggers action session:detail with the default context variables.

You can match this using the Action value in a policy statement .

Provides information about the current API key or session based API key.

Response

.email String Account email address.
.is_session Boolean Returns true if the API key used is a session based API key.
.access_id Integer Returns the access_id for the API key.

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

.ok true The request was successful. Session API key used to issue this API call has been invalidated.

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_name> Channel Info Object Information about a release channel

Channel Info Object

.channel String Channel name.
.created Integer Unix timestamp of when this release was created.
.version String Internal version number of the release. Sortable
.tag String OS Release Tag. Something like stable-XXXX. Sortable
.install.zip Object Download Info Object
.install.img.gz Object Download Info Object

Download Info Object

.hash Optional String SHA1 hash of the downloadable file.
.size Optional Integer Size of the downloadable file.
.url String Url where the file can be retrieved without authentication.
.customizable Boolean Whether or not this download can be customized with the OS customized download API

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:

install.zip A normal ZIP file that can be directly extracted to an empty SD card.
install.img.gz A gzip compress raw disk image that can be directly written to a block device. This is mainly useful for Compute Module installation where no user accessible SD card is available.

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
Triggers action download:customize with 3 request context variables available in addition to the default variables.

You can match this using the Action value in a policy statement .

Context value name Type Description
download:filename String The requested OS download filename.
download:channel String The requested OS channel.
download:add-connect-key Boolean Should a device-connect-key be added?

Creates a customized install.zip file with additional configuration settings or other added files.

Request parameters

channel String The requested OS release channel. This is used as the template for the generated download. Must be one of the channels returned in the OS release information API call.
filename String Template file for the download. Either install.zip or install.img.gz. Right now only customized zip files are possible. Whether or not a download can be customized is indicated by the customizable value returned in the OS release information API call.
connect Optional String If set to yes, the downloaded installation file will be configured so the device using this installation file will be automatically added the the account that made the API call. This is using the device connect mechanism.
/config/<filename> Optional String You can set the content of additional files in the /config directory of the generated download. Only files within /config can be added. The maximum total size of all files added is 1MB. So you can't add a big branding.mp4 or branding.jpg that way.

Response

.channel String The requested channel
.version String OS version used as the template for this download.
.download_url String The url of the generated download. It doesn't need authentication. You should not share the generated download url as the generated OS download might contain sensitive information like set WiFi passwords or your device connect key. The download uses chunked encoding, as the exact size isn't known beforehand.
.expires Integer The unix timestamp of when the generated download expires. Right now a download is valid for around 5 minutes.

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
Triggers action check:devices with the default context variables.

You can match this using the Action value in a policy statement .

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

filter:location String If set, only checks devices with a location name matching the provided pattern. You can use glob style patterns.
filter:description String If set, only checks devices with a description matching the provided pattern. You can use glob style patterns.
check:offline Number If set, provide the number of seconds after which a device is considered offline. A good number is 300, so 5 minutes. Settings this value too low (<120 seconds) might trigger a lot of false alarms.
check:maintenance String If set to any, devices with a Maintenance flags will be considered faulty.

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

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.

crop=default default option enforces the given output size and adds transparent space to fill the image. If no crop parameter is given, this is the default.
crop=smart Selects smart cropping. This enforces the given output size but might zoom in to 'interesting' areas of the image.
crop=none Disables cropping. none means no cropping happens. The size of the image is limited by the width/height or size parameter.
size=<size> The size must be given in pixels. The resulting thumbnail will be at most <size>x<size> pixels. <size> can be any value between 10 and 512 inclusive.
width=<size> Can be used to select the maximum width. This parameter takes precedence of the size given by the size parameter. The same max/min limits apply.
height=<size> Can be used to select the maximum height. This parameter takes precedence of the size given by the size parameter. The same max/min limits apply.

An example thumb url might look like this:

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