info-beamer.com hosted API


About

info-beamer.com exposes a lot of functionality using 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

The API requires authentication. You can use your API key for that. Use your API key as the password part of a basic auth request. In curl this might look like this:

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

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

Assign a device to an account. The PIN shown on the device welcome screen must be given. If there is a default setup selected 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 manually.

Request parameters

pin String The PIN of the device shown on the device welcome screen.

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

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

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>

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

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

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

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

Device reboot

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

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

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

.ok true The request was successful.
.lat Float Device latitude.
.lon Float Device longitude.
.address String Automatically detected address.
DELETE https://info-beamer.com/api/v1/device/<device_id>/location

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 command

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

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.

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.

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>

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

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

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.

Package details

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

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.
.webhooks Object Information about webhooks that can be triggered for this package.
.webhooks.sync Optional String If present, this url can be called without authentication to trigger a package source update. info-beamer hosted will check if there are updates available and import them.
.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>

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.
POST https://info-beamer.com/api/v1/package/<package_id>/sync

You cannot edit packages through info-beamer hosted. Package are always imported from a source. You specify that source 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 import that changes.

When a package changes, all setups that use the package will automatically use the updated package. All devices that use those setups will fetch the changes made.

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>

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

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

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

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"

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.

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.

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

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>

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>

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

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

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

Response

.assets List of Asset Info Objects All assets.

Asset details

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

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

tags Optional String A comma separated string with tags that will be assigned to the asset.
.userdata Optional JSON Object Custom data assigned to this asset. Must be JSON formatted. Up to 2k can be stored.
.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.

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>

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

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.

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.

Response

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

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.

Thumbnail urls

Various API responses include thumbnail urls. These urls point to a webservice that provides thumbnails for assets. You should not cache the returned urls as they might change. Only use the returned urls to show thumbnails next to their API response.

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

Setup expands

TODO