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

Search

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

List or search for zones.

Query Parameters

Name	Type	Description
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.

200

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

Name	Type	Description
name	string
description	string
tags	string
settings	object
triggers	array

200 Zone created.

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

Name	Type	Description
id	string	ID of the zone to retrieve.

200

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

Name	Type	Description
id	string	ID of the zone to update.

Request Body

Name	Type	Description
name	string
description	string
tags	string
settings	object
triggers	array

200

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

Name	Type	Description
id	string	ID of the zone to remove.

200