Zones

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

Zones

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

GET https://example.com/api/control/zones

List or search for zones.

Query Parameters

NameTypeDescription

q

string

A search filter to apply.

limit

integer

(default 20) Max results to return.

offset

integer

The offset within the result set.

tags

string

Return zones of this tag only.

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

Create

POST https://example.com/api/control/zones

Defines a new zone.

Request Body

NameTypeDescription

name

string

description

string

tags

string

settings

object

triggers

array

{
    "name": "ACA",
    "description": null,
    "tags": "org",
    "settings": {},
    "triggers": [],
    "created_at": 1555995992,
    "id": "zone-oOj2lGgszq"
}

Retrieve

GET https://example.com/api/control/zones/{id}

Lookup an existing zone.

Path Parameters

NameTypeDescription

id

string

ID of the zone to retrieve.

{
    "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"
}

Update

PUT https://example.com/api/control/zones/{id}

Updates metadata associated with a zone.

Path Parameters

NameTypeDescription

id

string

ID of the zone to update.

Request Body

NameTypeDescription

name

string

description

string

tags

string

settings

object

triggers

array

{
    "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://example.com/api/control/zones/{id}

Removes a zone.

Path Parameters

NameTypeDescription

id

string

ID of the zone to remove.

Last updated