Zones

The /zones endpoint provide access to discover, create and manage zones available. For more information on the role that zones play, see:

Model

Attribute

Type

Description

id

string

Unique ID the represents the zone.

name

string

Human readable name.

description

string

Long form description of the zone.

tags

string

Tags that provide context for the zone use. E.g. org, buidling, level.

settings

object

JSON object containing configuration linked to this zone.

triggers

array

List of trigger ID's to be applied to all systems that associate with this zone.

created_at

integer

Timestamp of creation.

Discovery

https://aca.example.com/api/control/zones
List or search for zones.
Request
Response
Query Parameters
q
optional
string
A search filter to apply.
limit
optional
integer
(default 20) Max results to return.
offset
optional
integer
The offset within the result set.
tags
optional
string
Return zones of this tag only.
200: OK
{
"total": 3,
"results": [
{
"name": "ACA",
"description": null,
"tags": "org",
"settings": {
"discovery_info": {
"buildings": [
{
"name": "Bourke St",
"zone_id": "zone-oOj4O_ijKl"
}
]
}
},
"triggers": [],
"created_at": 1555995992,
"id": "zone-oOj2lGgszq"
},
{
"name": "Bourke St",
"description": null,
"tags": "building",
"settings": {
"discovery_info": {
"levels": [
{
"level_id": "zone-oOj57Msk19",
"level_name": "Level 1",
"map_url": "assets/maps/level_01.svg"
}
]
}
},
"triggers": [],
"created_at": 1555996004,
"id": "zone-oOj4O_ijKl"
},
{
"name": "Level 1",
"description": null,
"tags": "level",
"settings": {},
"triggers": [],
"created_at": 1555996010,
"id": "zone-oOj57Msk19"
}
]
}

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://aca.example.com/api/control/zones
Defines a new zone.
Request
Response
Body Parameters
name
required
string
description
optional
string
tags
optional
string
settings
optional
object
triggers
optional
array
200: OK
Zone created.
{
"name": "ACA",
"description": null,
"tags": "org",
"settings": {},
"triggers": [],
"created_at": 1555995992,
"id": "zone-oOj2lGgszq"
}

get
Retrieve

https://aca.example.com/api/control/zones/{id}
Lookup an existing zone.
Request
Response
Path Parameters
id
required
string
ID of the zone to retrieve.
200: OK
{
"name": "ACA",
"description": null,
"tags": "org",
"settings": {
"discovery_info": {
"buildings": [
{
"name": "Bourke St",
"zone_id": "zone-oOj4O_ijKl"
}
]
}
},
"triggers": [],
"created_at": 1555995992,
"id": "zone-oOj2lGgszq"
}

put
Update

https://aca.example.com/api/control/zones/{id}
Updates metadata associated with a zone.
Request
Response
Path Parameters
id
required
string
ID of the zone to update.
Body Parameters
name
optional
string
description
optional
string
tags
optional
string
settings
optional
object
triggers
optional
array
200: OK
{
"name": "ACA",
"description": null,
"tags": "org",
"settings": {
"discovery_info": {
"buildings": [
{
"name": "Bourke St",
"zone_id": "zone-oOj4O_ijKl"
}
]
}
},
"triggers": [],
"created_at": 1555995992,
"id": "zone-oOj2lGgszq"
}

delete
Delete

https://aca.example.com/api/control/zones/{id}
Removes a zone.
Request
Response
Path Parameters
id
required
string
ID of the zone to remove.
200: OK