Systems

The /systems endpoint provides methods for discovering, creating and interacting systems within a deployment. For more on the role that systems play, please see:

All systems provide a base set of metadata that helps to describe their role and capabilities, as well as provide references to the modules they contain, and the zones they exist in.

Model

Attribute

Type

Description

id

string

The system's unique ID.

edge_id

string

ID of the preferred engine node to run on.

name

string

The system's primary identifier.

zones

array

Zone IDs that this system is a member of.

modules

array

Module ID's that this system contains.

description

string

Markdown formatted text that describes the system.

email

string

Calendar email that represents this system. Typically used for room scheduling / bookings.

capacity

integer

Number of people that can be accommodated in this space.

features

string

List of features in the room for searching and filtering spaces.

bookable

boolean

Flag for signifying the space as reservable.

installed_ui_devices

integer

Expected number of fixed installation touch panels.

settings

object

JSON object representing the system's configuration.

created_at

integer

Timestamp of creation time.

support_url

string

A URL linking to the primary interface for controlling this system.

version

integer

Incrementing counter for handling stale updates.v

http://aca.example.com/api/control/systems
Direct queries to the systems endpoint can be used to enumerate, or search for existing systems.
Request
Response
Query Parameters
q
optional
string
A search query for the system metadata.
limit
optional
integer
Max results to return (default 20).
offset
optional
integer
The offset within the result set.
zone_id
optional
string
Limit to systems within this zone.
module_id
optional
string
Limit to systems that contain this module.
200: OK
{
"total": 3,
"results": [
{
"edge_id": "edge-QC03B3OM",
"name": "Room 1",
"description": null,
"email": "room1@example.com",
"capacity": 10,
"features": "",
"bookable": true,
"installed_ui_devices": 0,
"zones": [
"zone-rGhCRp_aUD"
],
"modules": [
"mod-rJRCVYKVuB",
"mod-rJRGK21pya",
"mod-rJRHYsZExU"
],
"settings": {},
"created_at": 1562041110,
"support_url": null,
"version": 5,
"id": "sys-rJQQlR4Cn7"
},
{
"edge_id": "edge-QC03B3OM",
"name": "Room 2",
"description": null,
"email": "room2@example.com",
"capacity": 10,
"features": "",
"bookable": true,
"installed_ui_devices": 0,
"zones": [
"zone-rGhCRp_aUD"
],
"modules": [
"mod-rJRJOM27Kb",
"mod-rJRLE4_PQ7",
"mod-rJRLwe72Mo"
],
"settings": {},
"created_at": 1562041127,
"support_url": null,
"version": 4,
"id": "sys-rJQSySsELE"
},
{
"edge_id": "edge-QC03B3OM",
"name": "Room 3",
"description": null,
"email": "room3@example.com",
"capacity": 4,
"features": "",
"bookable": true,
"installed_ui_devices": 0,
"zones": [
"zone-rGhCRp_aUD"
],
"modules": [
"mod-rJRNrLDPNz",
"mod-rJRQ~JwE7U",
"mod-rJRV1qokbH"
],
"settings": {},
"created_at": 1562041145,
"support_url": null,
"version": 4,
"id": "sys-rJQVPIR9Uf"
}
]
]

Within the query parameter - q - a small query language is supported:

Operator

Action

+

Matches both terms.

|

Matches either terms.

-

Negates a single token.

"

Wraps tokens to form a phrase.

( and )

Provide precedence.

~N

Specifices edit distance (fuziness) after a word.

~N

Specifies slop amount (deviation) after a phrase.

post
Create

https://aca.example.com/api/control/systems
Request
Response
Body Parameters
edge_id
required
string
ID of the preferred engine node to run on.
name
required
string
System name.
description
optional
string
email
optional
string
capacity
optional
integer
bookable
optional
boolean
Default to false
installed_ui_devices
optional
integer
zones
required
array
modules
optional
string
settings
optional
string
support_url
optional
string
200: OK
{
"edge_id": "edge-QC03B3OM",
"name": "Example Room",
"description": "This is a room that does... things",
"email": "room@example.com",
"capacity": 10,
"features": "",
"bookable": true,
"installed_ui_devices": 0,
"zones": [
"zone-rGhCRp_aUD"
],
"modules": [],
"settings": {},
"created_at": 1562041110,
"support_url": "https://aca.example.com/foo",
"id": "sys-rJQQlR4Cn7"
}

get
Retrieve

https://aca.example/com/api/control/systems/{id}
Retrieve all metadata associated with the system.
Request
Response
Path Parameters
id
required
string
ID of the system to retrieve.
Query Parameters
complete
optional
boolean
Include full models of all modules and zones associated with the system rather than just ID's.
200: OK
{
"edge_id": "edge-QC03B3OM",
"name": "Example Room",
"description": "This is a room that does... things",
"email": "room@example.com",
"capacity": 10,
"features": "",
"bookable": true,
"installed_ui_devices": 0,
"zones": [
"zone-rGhCRp_aUD"
],
"modules": [
"mod-rJRCVYKVuB",
"mod-rJRGK21pya",
"mod-rJRHYsZExU"
],
"settings": {},
"created_at": 1562041110,
"support_url": "https://aca.example.com/foo",
"id": "sys-rJQQlR4Cn7"
}

put
Update

https://aca.example.com/api/control/systems/{id}
Update system attributes.
Request
Response
Path Parameters
id
optional
string
ID of the system to update.
Body Parameters
version
required
integer
The current system metadata version. This must match the current version attribute of the system and will be incrememented following a successful update.
name
optional
string
description
optional
string
email
optional
string
capacity
optional
integer
bookable
optional
boolean
installed_ui_devices
optional
integer
zones
optional
array
modules
optional
string
settings
optional
string
support_url
optional
string
200: OK
{
"edge_id": "edge-QC03B3OM",
"name": "Example Room",
"description": "This is a room that does... things",
"email": "room@example.com",
"capacity": 10,
"features": "",
"bookable": true,
"installed_ui_devices": 0,
"zones": [
"zone-rGhCRp_aUD"
],
"modules": [],
"settings": {},
"created_at": 1562041110,
"support_url": "https://aca.example.com/foo",
"id": "sys-rJQQlR4Cn7"
}

delete
Delete

https://aca.example/com/api/control/systems/{id}
Remove a system.
Request
Response
Path Parameters
id
required
string
ID of the system to retrieve.
200: OK