Systems

The /systems endpoint provides methods for discovering, creating and interacting with systems. For more on the role that systems play, see:
Systems
/key-concepts/systems
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 this space can accommodate.
features
string
List of features in the room for searching and filtering spaces.
bookable
boolean
Flag for signifying the space is bookable.
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.
support_url
string
A URL linking to the primary interface for controlling this system.
version
integer
Incremental counter for handling stale updates.
Discovery
get
Search
https://example.com/api/control/systems
Direct queries to the systems endpoint list, or search for existing systems.
Request
Response
Request
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.
Response
200: OK
A list of systems matching the search criteria.
{
    "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"
        }
    ]
}
Queries default to searching for any of the entered terms (words). A small query language provides the ability to structure complex queries.
Operator
Action
​
+
Matches both terms.
​
`
`
Matches either terms.
-
Negates a single token.
​
"
Wraps tokens to form a phrase.
​
( and )
Provide precedence.
​
~N
Specifies edit distance (fuzziness) after a word.
​
~N
Specifies slop amount (deviation) after a phrase.
​
Management
post
Create
https://example.com/api/control/systems
Defines a new system. Systems names must be unique within the instance they are running on and all systems must have at least one zone associated. All other attributes are optional at the time of creation.
Request
Response
Request
Body Parameters
name
required
string
​
zones
required
array
​
edge_id
optional
string
​
description
optional
string
​
email
optional
string
​
capacity
optional
integer
​
bookable
optional
boolean
​
installed_ui_devices
optional
integer
​
modules
optional
string
​
settings
optional
string
​
support_url
optional
string
​
Response
200: OK
{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further cotnext",
    "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://example.com/foo",
    "id": "sys-rJQQlR4Cn7"
}
get
Retrieve
https://example.com/api/control/systems/{id}
Retrieve all metadata associated with the system.
Request
Response
Request
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 their ID.
Response
200: OK
{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further context",
    "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://example.com/foo",
    "version": 3,
    "id": "sys-rJQQlR4Cn7"
}
put
Update
https://example.com/api/control/systems/{id}
Updates system attributes. Any selection of attributes form the request - unspecified items will keep their current values. All requests must include a version parameter that matches the current system version.
Request
Response
Request
Path Parameters
id
required
string
ID of the system to update.
Body Parameters
version
required
integer
The system metadata version. This must match the current version and increments following each 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
​
Response
200: OK
{
    "edge_id": "edge-QC03B3OM",
    "name": "Example Room",
    "description": "Example room description containing further context",
    "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://example.com/foo",
    "id": "sys-rJQQlR4Cn7"
}
409: Conflict
The specified version does not match the current system version.
​
delete
Delete
https://example.com/api/control/systems/{id}
Removes a system. This will stop, and remove any modules that are not associated with other systems.
Request
Response
Request
Path Parameters
id
required
string
ID of the system to retrieve.
Response
200: OK
​
Interaction
post
Start
https://example.com/api/control/systems/{id}/start
Starts all modules associated with the system.
Request
Response
Request
Path Parameters
id
required
string
ID of the system to start.
Response
200: OK
​
post
Stop
https://example.com/api/control/systems/{id}/stop
Stops all modules associated with the system.
Request
Response
Request
Path Parameters
id
required
string
ID of the system to stop.
Response
200: OK
​
post
Exec
https://example.com/api/control/systems/{id}/exec
Run behaviour exposed by a module. The associated method will execute and the response returned. If this includes asynchronous or long running behaviour, the result will be awaiting up until a timeout value.
Request
Response
Request
Path Parameters
id
required
string
ID of the system to execute within.a
Body Parameters
module
required
string
Class name of the module. i.e. `Display`, `Bookings` etc
index
optional
integer
(default 1) Module index in the system.
method
required
string
The name of the method to execute.
args
optional
array
Method arguments.
Response
200: OK
Response values are always wrapped in an outer array. This ensures that method which return primatives (strings, numbers, booleans or null) still provide a valid JSON response.
[]
get
State
https://example.com/api/control/systems/{id}/state
Query the state exposed by a module within the system.
Request
Response
Request
Path Parameters
id
required
string
ID of the system the module is in.
Query Parameters
module
required
string
Class name of the module.
index
optional
integer
(default 1) Index of the module.
lookup
optional
string
A status key of interest. If included, the response filters to this value.
Response
200: OK
{
  "foo": "abc",
  "bar": 42
}
get
Funcs
https://example.com/api/control/systems/{id}/funcs
Query the behaviour exposed by a module within the system.
Request
Response
Request
Path Parameters
id
required
string
ID of the system that the module is in.
Query Parameters
module
required
string
Class of the module.
index
optional
integer
(default 1) Index of the module.
Response
200: OK
{
  "function_name": {
    "arity": 1,
    "params": [
      "string"
    ]
  }
}
get
Count
https://example.com/api/control/systems/{id}/count
Counts the instances of a driver type within a system.
Request
Response
Request
Path Parameters
id
required
string
ID of the system to query.
Query Parameters
module
required
string
Class name of the modules to count.
Response
200: OK
{
  "count": 3
}
get
Types
https://example.com/api/control/systems/{id}/types
Query the types of modules available within a system.
Request
Response
Request
Path Parameters
id
required
string
ID of the system to query.
Response
200: OK
{
  "Booking": 1,
  "Display": 2,
  "VidConf": 1
}

API - Previous

Control

Modules

Last updated 6 months ago

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 this space can accommodate.
features	`string`	List of features in the room for searching and filtering spaces.
bookable	`boolean`	Flag for signifying the space is bookable.
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.
support_url	`string`	A URL linking to the primary interface for controlling this system.
version	`integer`	Incremental counter for handling stale updates.

Operator	Action
`+`	Matches both terms.
`	`	Matches either terms.
`-`	Negates a single token.
`"`	Wraps tokens to form a phrase.
`(` and `)`	Provide precedence.
`~N`	Specifies edit distance (fuzziness) after a word.
`~N`	Specifies slop amount (deviation) after a phrase.

Systems

Model

Discovery

getSearch

Management

postCreate

getRetrieve

putUpdate

deleteDelete

Interaction

postStart

postStop

postExec

getState

getFuncs

getCount

getTypes

get
Search

post
Create

get
Retrieve

put
Update

delete
Delete

post
Start

post
Stop

post
Exec

get
State

get
Funcs

get
Count

get
Types