Locations

Locations are the tree everything else hangs from: devices sit in them, episodes can be keyed by them, and reports are grouped by them. Three levels, one parent link, and an external_id you choose.

The location model

Properties

Name
external_id
Type
string
Description
Required. Your identifier for this place. It is the upsert key — sending the same one twice updates rather than duplicates.
Name
kind
Type
string
Description
Required. site, zone or point — the three levels of the hierarchy, from the broadest to the most precise.
Name
name
Type
string
Description
Required. The human-readable name, the one that shows up in the console and in reports.
Name
parent
Type
string
Description
Optional. The external_id of the parent location. Omit it for a site; provide it for everything below.

A location belongs to the source whose key declares or sends it, like every identifier. When two of your tools name the same place — QUAI-3 in one, dock_3 in the other — keep sending each its own; link them once in the console (“Same as…”, or a rule), and episodes, reports and habits count them as one place.

Order within a batch does not matter: parents are processed before their children. A parent that is neither in the batch nor already declared in the same source is rejected with unknown_parent_location — that item only, the rest of the batch still lands.

POST/v1/locations

Upsert locations

Bulk upsert of the location tree, keyed on external_id within the source, up to 500 per call.

Required attributes

Name
locations
Type
array
Description
Up to 500 locations.

Headers

Name
Authorization
Type
string
Description
Bearer <api_key>.

Rejection codes

Name
unknown_parent_location
Type
code
Description
The parent is neither in the batch nor already declared in this source.

Request

POST

/v1/locations

curl https://api.sinio.ai/v1/locations \
  -H "Authorization: Bearer $SINIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      { "external_id": "SITE-A", "kind": "site", "name": "Site A" },
      { "external_id": "SITE-A.HALL", "kind": "zone", "name": "Hall",
        "parent": "SITE-A" },
      { "external_id": "SITE-A.HALL.DOOR1", "kind": "point",
        "name": "Main door", "parent": "SITE-A.HALL" }
    ]
  }'

Response

{
  "accepted": 3,
  "rejected": 0,
  "rejections": []
}