Loopshore API

Version 0.67.0

Introduction

Loopshore API contains interfaces for reading and writing environmental sensor data from and to Loopshore cloud service.

APIs are HTTP based REST APIs. Only HTTPS is supported.

Terminology

Observation – a Physical or logical set of value, quantity and timestamp. Usually a measurement result.

Webhook – a way to deliver device observations to 3rd party servers.

API location

All endpoint paths in this document are relative to the base URL. For example, user/{user-id} means the full path is https://service.loopshore.com/api/user/{user-id}.

Authentication

There are four ways to authenticate to the API.

• Session cookie (web applications)
• Bearer token (mobile and programmatic clients)
• API keys
• Custom ingestion URL (only for sending observations)

Session cookie (web)

You can authenticate to the API using username and password. Obtaining these credentials is out of scope of this document. Workflow is as follows:

• Post credentials to /token API
• Save received session cookie
• The cookie is automatically sent with subsequent requests

Bearer token (mobile)

Mobile and programmatic clients use short-lived access tokens with long-lived refresh tokens. Workflow is as follows:

• Post credentials to /token API with grant_type set to "mobile"
• Receive an access token (15-minute lifetime) and a refresh token (30-day lifetime) in the response body
• Use the access token in the Authorization header: Authorization: Bearer <access_token>
• When the access token expires, use the refresh token at /token/refresh to obtain a new token pair
• Store the refresh token securely (e.g., device keychain/keystore)

Custom ingestion URL

Ask URL from Loopshore.

API keys

Users can use their credentials to acquire an API key that has the same privileges as the username and password. Using an API key might be easier, faster and less resource consuming than acquiring the session key for each request. Note that you have to handle the API keys with the same precautions as you handle the password.

A key can optionally be created as read-only. A read-only key keeps the same read access as its owner but cannot modify anything: every mutating request (any HTTP method other than GET/HEAD/OPTIONS) is rejected with 403 Forbidden. Read-only keys are recommended for integrations that only need to read data, so a leaked key cannot be used to change anything.

Authorization

Each user may access only what their roles give them, at the locations where the roles are granted; see User Roles. If you try to access a resource you don’t have access to, the API returns 403 Forbidden (or 404 Not Found where it does not reveal whether the resource exists). 401 Unauthorized means only that the request has no valid authentication; see Error handling. Ask the person who manages your user account, or Loopshore, if you think that you should have access to a resource.

Restrictions

A reasonable usage of APIs is expected from API users. Currently reasonable usage limit is once/minute/device/day, which should cover all the normal use cases. API access may be temporarily blocked if the user exceeds this amount.

If you want to exceed this restriction, contact Loopshore.

Concurrent history requests

Reading observation history is the heaviest work the API does, so the service accepts only a few history requests from one user account at a time, counted over all its API keys and sessions. This applies to Observation history, both cursor-based histories, every downsampled observations endpoint and Aggregated observations. A request over the limit waits a while for its turn before it is answered, so a client that sends its history requests one or two at a time never notices the limit.

When the service cannot take a request, it answers 429 Too Many Requests with {"error": "too_many_requests"} and a Retry-After header giving the seconds to wait. Wait at least that long and send the request again; do not retry in a tight loop.

A history read that takes too long is stopped and answered 504 Gateway Timeout with {"error": "query_timeout"}. Narrow the request, a shorter time window or a single quantity, and send it again.

Example 1

User has access to two devices, that each report new measurements every 10 minutes. User polls the latest measurements for each device every 5 minutes.

API Usage

• Devices: devices×hours×hourly_rate = 2×24×(60/10) = 288
• History: devices×hours×hourly_rate = 2×24×(60/5) = 576
• Total: 288+576 = 864 requests/24h
• Limit: devices×hours×minutes = 2×24×60 = 2880 requests/24h

24h requests (864) is well below the limit (2880) so API usage is ok.

Example 2

User has access to two devices, that each report new measurements every 10 minutes. User wants to load a year’s worth of history data from both devices. User fetches 15 different quantities from each device.

API Usage

• Devices: devices×hours×hourly_rate = 2×24×(60/10) = 288
• History:
  • Measurement in a API call (5000 limit): (5000/15) = 333
  • Hours in API call: 333/(60/10) = 56
  • API calls needed to get 1 year history: (365×24)/56 = 158
• Total: 288+158 = 446 requests
• Limit: devices×hours×minutes = 2×24×60 = 2880

Requests (446) is below the limit (2880) so API usage is ok.

API descriptions

Content types

APIs are HTTP REST APIs. APIs accept two types of content: JSON and transit+JSON. If user does not give Content-Type (in POST) or Accept header (in GET), service assumes JSON.

Error handling

The API uses standard HTTP status codes to indicate success or failure:

A refused request answers 404 when the resource doesn’t exist or is outside what you can see, and 403 when you can see it but aren’t allowed the action. This applies to locations, groups, devices, installations and users.

Error responses are returned as JSON. The format varies but typically includes an error or message field:

{
  "error": "Error type",
  "message": "Detailed description"
}

Common error examples:

Authentication missing, expired or invalid (no session, an expired or invalid token, or an unknown API key) returns 401 on every endpoint that requires authentication, with a WWW-Authenticate: Bearer header. The body is empty, except for an unknown API key, which returns {"error": "invalid_api_key"}. A request with an x-api-key header is authenticated by that key only: if the key is unknown, a session cookie or Bearer token in the same request is not used. A 401 never means that you lack permission for the resource; that is a 403.

Validation failure (e.g., creating user with invalid data):

{"error": "Bad Request", "message": "Unsupported language"}

Resource not found or outside your scope:

"No such user"

Access to the service has ended for the user’s organization (all authenticated requests, login and token refresh):

{"error": "group_suspended"}

The user has been suspended (see Suspend user) (all authenticated requests, login and token refresh):

{"error": "user_suspended"}

A share link no longer works (all requests made with it). This is the only error a share link gives for its location being deleted or archived, the location being outside what the link’s owner can see, or the owner or their organization being suspended:

{"error": "share_unavailable"}

Duplicate username:

{"error": "Conflict", "message": "Username already exists"}

Invalid path format when creating location:

{"error": "Bad Request", "message": "Path must match pattern: label.label.label"}

Error handling guidance:

• Check the status code first, then parse the response body for details
• Response body may be a JSON object or a plain string
• For 401 errors, re-authenticate (or refresh the access token) and retry once
• For 403 with {"error": "group_suspended"}, don’t re-authenticate or retry: the organization’s access to the service has ended, and it stays blocked until Loopshore restores it
• For 403 with {"error": "user_suspended"}, don’t re-authenticate or retry: the user has been suspended, and it stays blocked until someone who manages the user unsuspends them
• For 403 with {"error": "share_unavailable"}, don’t retry: tell the viewer that the link no longer works. It works again only if its owner regains access to the shared location
• For 400/403/404 errors, fix the request (don’t retry)
• For 5xx errors, retry with exponential backoff

Known quantities

APIs are designed so that you can practically send any kind of information/observations to the system and fetch those via APIs. There is however, some predefined and known data types that have special meaning. These should be used when possible, because then for example the user interface recognizes the types.

Quantities and units are case sensitive.

Some quantities are calculated by system if not sent by device and source data is available. These are marked with asterisk (*) in the list below.

Note! System also recognizes quantities that are post fixed with _<number>. So you can for example send three temperatures from the same device by naming them temperature, temperature_1 and temperature_1234.

User APIs STABLE

These APIs are available to all authenticated users for reading and writing observation data. Each returns only what your roles give you (see User Roles).

Login STABLE

The login endpoint supports two modes depending on the grant_type parameter.

Cookie mode (default)

When grant_type is omitted or "cookie", the response sets a session cookie. This is the mode used by web applications.

Example request

{
  "name": "user@example.com",
  "password": "secret"
}

Example response header

Set-Cookie: jabster_token=<token>;Max-Age=43200

Example use of cookie in a request

Cookie: jabster_token=<token>

Mobile mode

When grant_type is "mobile", the response returns access and refresh tokens in the body. No cookie is set.

Example request

{
  "name": "user@example.com",
  "password": "secret",
  "grant_type": "mobile",
  "device_info": "iPhone 15 Pro"
}

Example response

{
  "user": "user@example.com",
  "ts": "2025-01-15T10:30:00Z",
  "access_token": "eyJhbGciOiJIUzUxMiJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "token_type": "Bearer",
  "expires_in": 900
}

Response fields (mobile mode):

Example use of access token in a request

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

Error responses:

Refresh token STABLE

Exchange a valid refresh token for a new access token and refresh token pair. This endpoint does not require authentication — the refresh token itself serves as the credential.

Token rotation: Each refresh request invalidates the old refresh token and issues a new one. Always store and use the latest refresh token.

Reuse detection: If a previously rotated (invalidated) refresh token is used, all tokens in the session are revoked for security. The user must log in again.

Example request

{
  "refresh_token": "a1b2c3d4e5f6..."
}

Example response

{
  "access_token": "eyJhbGciOiJIUzUxMiJ9...",
  "refresh_token": "f6e5d4c3b2a1...",
  "token_type": "Bearer",
  "expires_in": 900
}

Error responses:

Acquire apikey STABLE

Acquire an apikey (random hexstring) that can be used instead of session style login. key-name is a documentary string that can be used to identify different keys. Purpose and context should be omitted.

Set read-only to true to create a key that can read data but cannot perform any modifications (see API keys). It defaults to false. A read-only key still has the same read access as its owner.

Response contains a secret-key that can be used in HTTP header to authenticate a user. Treat the secret-key with the same precautions as a password.

There is no way to recover a lost secret-key. In case a secret-key is lost, make a new one and preferably delete the lost key from the service.

id is used to identify a key in other APIs.

Example request

{
  "key-name": "my-read-only-key",
  "read-only": true
}

Example response

{
  "id": 123,
  "secret-key": "ccb22ee3fe90ce30d20654ee214307755806f53dbb84",
  "read-only": true
}

Notes:

1. The purpose and context request fields should be omitted. They refer to restricted access modes that are not relevant for the APIs documented here.

apikey usage

Apikey is used by putting the key to HTTP header with name x-api-key.

Example header

x-api-key:ccb22ee3fe90ce30d20654ee214307755806f53dbb84

List apikeys STABLE

List all the user’s api-keys with key-name and id. Each entry also includes read_only, indicating whether the key is restricted to read-only access.

Example response

[{
  "id": 123,
  "key-name": "my-api-key",
  "purpose": "all",
  "read_only": false
},
{
  "id": 567,
  "key-name": "my-iframe-view-key",
  "purpose": "sharer",
  "context": {"any": "thing"},
  "read_only": false
},
{
  "id": 891,
  "key-name": "my-read-only-key",
  "purpose": "all",
  "read_only": true
}]

Remove apikey STABLE

Removes an api-key from the service.

Example request

{
  "id": 123
}

Observation history STABLE

Returns all observations for given device-id from the start timestamp to current time.

Result is limited to 5000 observations.

Optionally, end timestamp and quantity filter can be given.

start time is inclusive and end time is exclusive. Both are points in time, so a UTC offset is applied: end=2021-03-01T00:00:00+02:00 ends the window at 22:00 UTC on 28 February. Encode the + as %2B in the URL.

Observations are ordered by timestamp, and observations with the same timestamp by quantity. When the result reaches the 5000-observation limit, the observations at its last timestamp may be cut short. Page by fixed time windows that stay under the limit, as in the usage example below. Starting the next request from the last returned timestamp can repeat or miss observations.

Access. You receive observations from the periods the device was installed at a location you have access to. An org-admin instead receives observations from the periods the device belonged to their organization, wherever it was installed. Outside these periods the result is an empty list.

Result is a JSON list of objects where each object presents a single quantity-value-time observation. Timestamp, value and quantity are always present. Unit is optional.

Response example

[
  {
    "timestamp": "2021-02-03T11:29:31.229Z",
    "value": 21.4,
    "quantity": "temperature",
    "unit": "C"
  },
  {
    "timestamp": "2021-02-03T11:23:12Z",
    "value": 442,
    "quantity": "co2",
    "unit": "PPM"
  }
]

Usage example

You want to get one year history of temperature from a device. You know that a device sends data mostly with once / 10 minute intervals. This means that you get 6×24=144 datapoints in a day and 144×30=4320 datapoints in a month. This falls within API 5000 result rows limit.

Because start time is inclusive and end time is exclusive, you can now call the API like this:

/read/device/my-device-id?start=2020-01-01T00%3A00%3A00Z&quantity=temperature&end=2020-02-01T00%3A00%3A00Z

/read/device/my-device-id?start=2020-02-01T00%3A00%3A00Z&quantity=temperature&end=2020-03-01T00%3A00%3A00Z

Latest observations STABLE

Returns the latest observations of each quantity for given device-id.

This API is optimized for “poll latest observations” use case.

The same access rule as in Observation history applies. A device currently installed at an archived location returns an empty list.

Response example

[
  {
    "timestamp": "2021-02-03T11:29:31.229Z",
    "value": 21.4,
    "quantity": "temperature",
    "unit": "C"
  }
]

Subscribe observations STABLE

Posts a new webhook either given device-id or scope.

Webhooks or subscriptions are used to subscribe data to 3rd party server in real time. When observations from device arrive to Loopshore service, it immediately forwards them to all interested stakeholders.

Webhook must contain a valid url where the data is to be sent.

Webhooks can be targeted to single device-ids or all the devices that user has access to (scope). Only valid value for scope is “all”. “all” covers every device installed at a location where you hold a tier from viewer up; for an org-admin, every location of their organization. Observations from devices at archived locations are not sent.

Optionally HTTP message sent from Loopshore can contain custom headers (x-headers).

Simple example for single device

{
  "url": "http://my-insecure-server.io/my-api",
  "device-id": "my-device-id"
}

More complex example for all devices with custom headers

{
  "url": "https://my-secure-server.io/my-api",
  "scope": "all",
  "description": "Just for testing, to be deleted",
  "x-headers": {
    "apikey": "secret",
    "target": "all-loopshore-devices"
  }
}

Response

Response contains all the data that was posted to API plus id and nonce fields.

id - can be used to identify this particular webhook in other APIs.

nonce - is a random string that is sent along with forwarded observations and it can be used to identify what hook generated the POST.

Example response

{
  "id": "a0c03d18-378e-4326-b1d5-b47d9248be1e",
  "url": "https://my-secure-server.io/my-api",
  "scope": "all",
  "description": "Just for testing, to be deleted",
  "nonce": "_izF930v",
  "x-headers": {
    "apikey": "secret",
    "target": "all-loopshore-devices"
  },
  "device-id": null
}

List subscriptions STABLE

This API can be used to list all the subscriptions/webhooks.

Example response

[{
  "id": "a0c03d18-378e-4326-b1d5-b47d9248be1e",
  "url": "https://my-secure-server.io/my-api",
  "scope": "all",
  "description": "Just for testing, to be deleted",
  "nonce": "_izF930v",
  "x-headers": {
    "apikey": "secret",
    "target": "all-loopshore-devices"
  },
  "device-id": null,
  "last-delivered-at": "2024-06-01T00:00:00Z"
}]

last-delivered-at – last time an observation was delivered to the url successfully, or null if never recorded. Updated at most once a day, so it can lag by up to a day.

Cancel observation subscription STABLE

This API can be used to remove a subscription.

Test subscriptions STABLE

Sends a test message to webhook url.

You can test your webhook counterpart by posting a custom message to this API. Service then forwards the message to your server.

nonce – is the nonce for the webhook id.

data – any valid JSON. When real message arrives, data contains the same data that came in to the system via Send observations API.

Example message sent to url server

{
  "nonce": "_izF930v",
  "data": {"my": "test data"}
}

Example of message identical to real data

{
  "nonce": "_izF930v",
  "data": {
    "device-id": "123456789",
    "observations": [
      {
        "unit": "C",
        "value": 19.24,
        "quantity": "temperature",
        "timestamp": "2021-02-03T11:23:12Z"
      }
    ]
  }
}

Send observations STABLE

Posts new observations for given device-id. For getting your own token, contact Loopshore.

Body example

{
  "device-id": "my-device-id",
  "observations": [
    {
      "timestamp": "2021-02-03T11:29:31.229Z",
      "value": 21.4,
      "quantity": "temperature",
      "unit": "C"
    }
  ]
}

Extended User APIs DRAFT

These APIs are available to all authenticated users, and each returns only what your roles give you (see User Roles). Reading needs only that you see the location; an endpoint that needs more says so on its Required role line. They extend the stable APIs above with additional features for managing user preferences, browsing locations, reading measurement data, configuring alarms, and more.

Self-Service DRAFT

Get current user DRAFT

Returns the profile data of the currently authenticated user.

Example response

{
  "id": 1,
  "name": "user@example.com",
  "role": "user",
  "email": "user@example.com",
  "emailConfirmed": true,
  "language": "fi",
  "theme": "loopshore",
  "profile": {},
  "phonenum": "+358501234567",
  "lastlogin": "2024-06-01T10:30:00Z",
  "last-credential-login-at": "2024-05-28T08:00:00Z",
  "last-refresh-at": "2024-06-01T10:30:00Z",
  "features": {"ai-helper": false},
  "permissions": {
    "locations": [
      {
        "location-id": 5,
        "path": "root.customer.hq",
        "permissions": ["alarm/subscribe-status", "derived-quantity/manage", "location/display-settings",
                        "location/layout", "location/rename", "location/view", "note/write",
                        "personal/api-keys", "personal/share-links", "personal/webhooks"]
      }
    ]
  }
}

Response fields:

Users who manage users (org-admin, or building-admin at some location) additionally receive last-device-info (the device_info string from the most recent mobile session); others don’t. Get user has the full shape. The user management endpoints also count API key use, webhook deliveries and alarms sent in lastlogin; this endpoint does not.

Permissions

permissions lists what you may do, per scope. Use it to decide which actions to offer; the API still checks every request. role doesn’t tell what you may do.

At an archived location only location/edit applies. Permission names:

New permissions may be added; ignore names you don’t know.

Logout DRAFT

Clears the session cookie and logs the user out. Returns "logout" on success.

Mobile clients should include the refresh_token in the request body to revoke it server-side. If omitted, only the cookie is cleared (web logout behavior).

Example request (mobile)

{
  "refresh_token": "a1b2c3d4e5f6..."
}

Set language DRAFT

Set the UI language preference for the current user. The setting is synced — the same language applies on web and mobile.

Example request

{
  "language": "fi"
}

Success response: Returns the full user object (same as GET whoami).

Update settings DRAFT

Update display preferences: units, and the measurements tree preference tree-locations (see Profile). All fields are optional — only include fields you want to change; the others stay. Settings are synced across web and mobile. A value that can’t be stored answers 400.

Example request

{
  "temperature-unit": "celsius",
  "pressure-unit": "hPa"
}

Success response: Returns the full user object (same as GET whoami).

Set phone number DRAFT

Set or update the user’s phone number. Phone number must be in international format starting with +. Send an empty string "" to remove the phone number.

If the phone number is new, SMS verification is required. A 6-digit verification code is sent via SMS.

Example request

{
  "phonenum": "+358501234567"
}

Example response

{
  "verification-needed": true
}

If verification-needed is true, call the verify endpoint with the code received via SMS.

Verify phone number DRAFT

Verify the phone number using the 6-digit code received via SMS. Returns 200 on success, 400 if the code is incorrect.

Example request

{
  "phone-num-verification-code": 123456
}

Request password reset DRAFT

Request a password reset link to be sent to the given email address. This is a public endpoint — no authentication required. The reset token is short-lived (1 hour) since the user is expected to act on the email immediately, and repeated requests for the same account are rate-limited. The response is always the same regardless of whether the email exists, to prevent user enumeration. For reset emails sent by someone who manages the user, with longer-lived tokens,, see POST password/send-reset-email under Admin APIs.

Example request

{
  "email": "user@example.com"
}

Example response

{
  "message": "If an account with that email exists, a password reset link has been sent."
}

Location Tree & Details DRAFT

Locations are organized hierarchically: site → building → floor → room. The tree API returns all locations the current user has access to, with their children nested recursively. See the Path and Tag sections under Admin APIs for details on the hierarchy model.

Get location tree DRAFT

Returns all locations that the current user has access to, organized as a recursive tree structure. Each node contains its children, forming the complete hierarchy from top-level sites down to individual rooms. Archived locations are excluded from this response.

The tree starts from the locations selected for your user. If none of the selected locations is available to you (for example, none is selected, or all of them are archived), the tree contains every location you can view.

For a share link, the tree is the shared location alone, with no children: a share link reaches only that location.

Example response

[
  {
    "id": 5,
    "path": "campus.office",
    "name": "Office Building",
    "data": {},
    "uuid": "550e8400-e29b-41d4-a716-446655440001",
    "tag": "building",
    "parent": 1,
    "images": ["facade"],
    "children": [
      {
        "id": 10,
        "path": "campus.office.floor_1",
        "name": "Floor 1",
        "data": {},
        "uuid": "550e8400-e29b-41d4-a716-446655440002",
        "tag": "floor",
        "parent": 5,
        "images": ["blueprint"],
        "children": [
          {
            "id": 15,
            "path": "campus.office.floor_1.room_101",
            "name": "Meeting Room",
            "data": {},
            "uuid": "550e8400-e29b-41d4-a716-446655440003",
            "tag": "room",
            "parent": 10,
            "images": [null],
            "children": []
          }
        ]
      }
    ]
  }
]

Node fields:

Get location details DRAFT

Get details for a single location. Returns the same fields as a tree node but without parent and children. Returns 404 for archived locations.

Example response

{
  "id": 5,
  "path": "campus.office",
  "name": "Office Building",
  "data": {"address": "Example Street 1"},
  "uuid": "550e8400-e29b-41d4-a716-446655440001",
  "tag": "building",
  "images": ["facade"]
}

The images field has the same meaning as on the tree endpoint above — see the images row in the Node fields table.

List devices at location DRAFT

List devices currently installed at the given location. Returns only the most recent installation per device.

product-name is the human-readable product name (e.g. "Loop One") resolved server-side from the first two characters of device-type. It is null when the prefix is not in the product catalog (e.g. legacy or third-party devices).

Example response

[
  {
    "description": "Air quality monitor",
    "device-id": "device-001",
    "device-type": "L103EWC0301",
    "product-name": "Loop One",
    "installation-time": "2024-01-15T10:30:00Z"
  }
]

Reading Observation Data DRAFT

The stable APIs above cover basic observation reads (history with 5000-row limit and latest values per device). This section documents additional ways to read observation data that are more suitable for graphing, analytics, and large time ranges.

Three approaches to reading observation data:

1. Raw reads — Return individual observations. Use the stable Observation history API for small time ranges (up to 5000 rows), or the cursor-based streaming API below for large ranges.
2. Downsampled reads — Return a fixed number of data points spread across a time range. Ideal for rendering line charts without sending millions of points to the client.
3. Aggregated reads — Return time-bucketed statistics (min, max, average, count). Ideal for summary views, bar charts, and very long time ranges.

Device-based vs location-based queries:

• Device-based APIs (e.g., observation/read-v2/device/{device-id}) return data from a single device.
• Location-based APIs (e.g., location/{id}/observations/downsampled) return data from all devices installed at the location during the queried time range. Each returned point carries a device-id, so a location with two devices reporting the same quantity yields points from both in one time-ordered series.

Choosing an endpoint

Prefer a downsampled or aggregated read whenever the data is destined for a chart. One year of 10-minute data is roughly 52 000 points per device, and a chart a few hundred pixels wide cannot display more than a few hundred of them.

Incomplete reads. The downsampled endpoints read the raw observations behind your window before reducing them. If a range is so large or so dense that they cannot read all of it, the response carries "truncated": true and the series — along with any min/max/mean — describes only the part that was read. The field is absent otherwise, so its presence always means something. In practice this needs a range of several years on a location with an unusually high reporting rate; if you see it, the range wants the aggregated endpoint instead.

Sizing samples. For the downsampled endpoints, set samples to the chart’s width in pixels — asking for more points than the chart has pixels only costs bandwidth. The aggregated endpoint treats samples differently; see Aggregated observations below before choosing a value there.

Observation history V2 (cursor-based) DRAFT

Cursor-based paginated read for large time ranges without downsampling. Unlike the stable V1 API (limited to 5000 rows), this API supports unlimited data retrieval by paginating through results.

start is inclusive, cursor and end are exclusive, so consecutive windows whose end is the next start return each observation once.

Usage: Make the first request with start (and optionally end and quantity). If has-more is true in the response, make another request with the returned cursor value to get the next page. Repeat until has-more is false.

Example response

{
  "observations": [
    {
      "dt": "2024-01-15T14:30:00Z",
      "quantity": "temperature",
      "value": 21.5,
      "unit": "C"
    },
    {
      "dt": "2024-01-15T14:30:00Z",
      "quantity": "co2",
      "value": 442,
      "unit": "ppm"
    }
  ],
  "has-more": true,
  "cursor": "2024-01-15T14:30:00Z"
}

Note: The V2 API uses dt (ISO 8601 string) for timestamps, unlike V1 which uses timestamp (epoch). The cursor field is the timestamp of the last observation in the page — pass it back to continue.

Location observation history V2 (cursor-based) DRAFT

Same as device-level V2 streaming, but returns observations from all devices at the given location. Each observation includes a device-id field to identify the source device. Same pagination pattern — use cursor to get next pages.

Downsampled observations DRAFT

Returns observations downsampled to at most samples data points using the Largest-Triangle-Three-Buckets (LTTB) algorithm, which preserves the visual shape of the series while dramatically reducing the number of points. Values above 2000 are reduced to 2000. This is the recommended endpoint for drawing a location’s line chart. There is no limit on the length of the requested time range.

Alongside the points, the response carries min, max and mean for the window. These are computed over all observations in the range, before downsampling — so they remain accurate even at low samples values, and can be used to set a stable Y-axis or show a “peak was X” readout without a second request.

If no devices were installed at the location during the requested window — or none of them reported that quantity — all four fields come back empty (observations is [], the rest null). This is a normal result, not an error.

Example response

{
  "min": {
    "timestamp": "2024-01-15T04:20:00Z",
    "value": 18.1,
    "device-id": "device-001"
  },
  "max": {
    "timestamp": "2024-01-15T15:10:00Z",
    "value": 24.9,
    "device-id": "device-002"
  },
  "mean": 21.4,
  "observations": [
    {
      "timestamp": "2024-01-15T14:30:00Z",
      "value": 21.5,
      "device-id": "device-001"
    },
    {
      "timestamp": "2024-01-15T14:40:00Z",
      "value": 21.8,
      "device-id": "device-001"
    }
  ]
}

Downsampled observations, points only DRAFT

A narrower variant of the endpoint above: same LTTB downsampling and the same handling of long ranges, but the response contains only the observations list — no window min, max or mean.

As with the endpoint above, the response carries "truncated": true if the read could not cover the whole range.

Note: The -v2 suffix denotes this different response shape, not a newer generation of the API. Prefer location/{id}/observations/downsampled when you also want the window statistics.

Example response

{
  "observations": [
    {
      "timestamp": "2024-01-15T14:30:00Z",
      "value": 21.5,
      "device-id": "device-001"
    },
    {
      "timestamp": "2024-01-15T14:40:00Z",
      "value": 21.8,
      "device-id": "device-001"
    }
  ]
}

Device downsampled observations DRAFT

Returns LTTB-downsampled observations for a single device and a single quantity over the requested time window. Useful when you already know the device and want a chart-ready time series without first looking up its current location. There is no limit on the length of the requested range. Values of samples above 2000 are silently reduced to 2000.

You receive data only for the devices and time windows you have access to, as in Observation history. If the caller has no access for the device in the requested window, an empty observations list is returned.

Example response

{
  "observations": [
    { "timestamp": "2024-10-01T08:30:00Z", "value": 21.5 },
    { "timestamp": "2024-10-01T09:00:00Z", "value": 21.8 }
  ]
}

Aggregated observations DRAFT

Returns time-bucketed aggregate statistics (min, max, average, count), optionally downsampled to samples points. Buckets are aligned to whole UTC hours or whole UTC days — note that a day bucket therefore starts at 00:00 UTC, not at local midnight.

samples has two effects here, which is worth understanding before choosing a value:

1. It selects the bucket period. If the requested range is longer in hours than samples, day buckets are returned; otherwise hour buckets are. Unlike the downsampled endpoints, samples is not capped here — it has to be free to exceed 2000 so that long ranges can still ask for hour buckets.
2. It is also the LTTB target applied to the resulting buckets.

Passing the chart’s pixel width — the right choice for the downsampled endpoints — therefore has a side effect here: a narrow chart flips to day buckets sooner than a wide one. Instead, decide which period you want and set samples at or above the number of buckets that period produces, so no thinning takes place:

• One year of day buckets: any samples from 365 to 8759 → 365 buckets returned
• 32 days of hour buckets: samples of 768 or more → 768 buckets returned

Then thin client-side if you want fewer points. This matters if you intend to draw a min–max band: LTTB selects buckets by their average, so letting it thin the series drops the buckets holding the extremes and the band will understate the true peaks.

Aggregates are produced by a background analysis process and are stored per location, so they are already combined across all devices at that location.

Example response

{
  "min": {
    "timestamp": "2024-01-15T03:00:00Z",
    "avg": 19.5,
    "min": 18.0,
    "max": 20.5,
    "count": 6,
    "period": "hour"
  },
  "max": {
    "timestamp": "2024-01-15T14:00:00Z",
    "avg": 23.5,
    "min": 22.0,
    "max": 25.0,
    "count": 8,
    "period": "hour"
  },
  "avg": 21.8,
  "aggregates": [
    {
      "timestamp": "2024-01-15T08:00:00Z",
      "avg": 21.2,
      "min": 20.0,
      "max": 22.5,
      "count": 6,
      "period": "hour",
      "quantity": "temperature"
    }
  ],
  "analysis-in-progress": false
}

Note: The range is filtered as start ≤ bucket < end, i.e. the end bound is exclusive. A window ending exactly on a bucket boundary — midnight, for day buckets — will not include the bucket starting at that instant. The observation endpoints, by contrast, include their end instant.

Export observations as CSV DRAFT

Downloads observations at the given location as a CSV file, over the [start, end] window (end defaults to now). The response is streamed, so arbitrarily large time ranges can be exported. With no optional parameters the output is unchanged from before: one column per quantity the location’s devices have ever reported (sorted), a single UTC dt column, and device_id and name columns, comma-separated.

Columns. Precedence: quantities (an explicit comma-separated list) wins and fully determines the columns and order — compact is ignored when it is given, and a listed quantity with no data in the window still appears as an empty column. Otherwise compact=true includes only quantities that have data within [start, end]. Otherwise (default) every quantity the devices have ever reported is included.

Timestamps. utc and local are independent columns. The default (utc=true, local=false) emits a single dt column in UTC. Enabling local adds a column in the tz timezone; tz is required when local=true. With both enabled the columns are named dt_utc and dt_local.

Format. separator sets the field delimiter and decimal the decimal mark for numeric values; they must differ. bom=true prepends a UTF-8 byte-order mark so Excel detects UTF-8 (a Finnish/Swedish Excel file is separator=;, decimal=,, bom=true).

Preview. preview=N returns only the first N output rows (used by the export dialog’s preview pane).

Returns 400 if separator equals decimal, if local=true without a valid tz, or if quantities lists more than 200 entries. Returns 503 if too many CSV exports are already in progress (retry shortly).

Quantities & Measurements DRAFT

These APIs return quantity metadata and latest measurement values for locations. Unlike the device-based APIs in the stable section, these use path-based queries — you provide a location path (e.g., campus.office) and get data for all locations under that path.

Key concepts:

• Path parameter: A dot-separated location path (e.g., campus.office). Returns data for all leaf nodes (rooms) under that path.
• Exclusive quantities: A per-location whitelist that controls which quantities are shown in the UI. When respect-exclusive is true (default), only whitelisted quantities are returned.
• Hidden quantities: Quantities marked as hidden in the system configuration. Use include-hidden=true to include them.
• System quantities: Device health metrics (batt, rsrp, snr) that are not regular measurements. Use include-system=true to include them.

Get quantity metadata DRAFT

Returns metadata about all known quantities and per-location configuration for all locations under the given path. This includes threshold configurations, custom display names, and visibility settings.

Time window (start + end): When both are provided, each location entry includes an observed-quantities field listing every quantity identifier that was produced by any device whose installation at that location overlaps the [start, end] window. Use this when you need to know which quantities are worth querying historically for a location in a given time range — it surfaces data from devices that are no longer currently installed. Both parameters must be given together; if either is omitted, no observed-quantities is attached.

Example response

{
  "quantities": {
    "temperature": {
      "unit": "C",
      "shown": true,
      "chart-type": "line",
      "delay-minutes": 30,
      "hysteresis-minutes": 15,
      "default-thresholds": {
        "S1+": [[15, 0], [20, 2], [20.5, 5], [25, 5], [27, 2], [32, 0]],
        "S2+": [[15, 0], [20, 2], [20.5, 5], [26, 5], [27, 2], [32, 0]],
        "S3+": [[15, 0], [20, 2], [20.5, 5], [26, 5], [27, 2], [32, 0]]
      }
    },
    "co2": {
      "unit": "ppm",
      "shown": true,
      "chart-type": "line",
      "default-thresholds": {
        "S1+": [[0, 5], [750, 5], [950, 2], [2000, 0]],
        "S2+": [[0, 5], [950, 5], [1200, 2], [2000, 0]],
        "S3+": [[0, 5], [1200, 5], [1550, 2], [2000, 0]]
      }
    },
    "batt": {
      "unit": "%",
      "shown": false,
      "default-thresholds": {
        "default": [[0, 0], [11, 2], [30, 5], [100, 5]]
      }
    }
  },
  "locations": {
    "15": {
      "location-id": 15,
      "path": "campus.office.floor_1.room_101",
      "name": "Meeting Room",
      "tag": "room",
      "location-thresholds": {
        "temperature": {
          "aqi-curve": [[15.0, 0.0], [20.7, 5.0], [21.3, 5.0], [27.0, 0.0]]
        }
      },
      "exclusive-quantities": ["temperature", "humidity", "co2"],
      "alternative-names": {
        "temperature": "Supply Air Temp"
      },
      "observed-quantities": ["temperature", "humidity", "co2", "batt"]
    }
  }
}

The observed-quantities field appears only when start and end were both provided.

Response fields:

The quantities map contains global quantity definitions keyed by identifier. The locations map contains per-location data keyed by location ID.

Quantity fields (entries under quantities.<identifier>):

Location fields (entries under locations.<id>):

Get latest measurements DRAFT

Returns the most recent measurement value for each quantity at each location under the given path. This is the primary API for displaying current values across a building or site.

Example response

{
  "locations": {
    "15": {
      "location-id": 15,
      "path": "campus.office.floor_1.room_101",
      "name": "Meeting Room",
      "values": {
        "temperature": {
          "value": 21.4,
          "datetime": "2024-01-15T14:30:00Z",
          "unit": "C",
          "device-id": "device-001",
          "device-type": "L103EWC0301",
          "product-name": "Loop One"
        },
        "co2": {
          "value": 442,
          "datetime": "2024-01-15T14:30:00Z",
          "unit": "ppm"
        }
      },
      "device": {
        "device-id": "device-001",
        "device-type": "L103EWC0301",
        "product-name": "Loop One",
        "notable-flags": [
          { "key": "notable.dense_interval", "tone": "warn", "params": { "interval": 120 } }
        ]
      }
    }
  }
}

Note: Device metadata is returned in two places, both only when include-device-info=true:

• The location-level device object reflects the currently installed device at that location. It is sourced from the installation record, so it is present whenever a device is installed — independent of whether that device has reported any measurements. Omitted when no device is currently installed.
• The per-value device-id, device-type, and product-name fields identify the device that produced each individual measurement.
• The device object’s optional notable-flags array highlights attention-worthy configuration settings of the installed device. It is present for every caller except a share link, and only when the device has at least one flag. See Notable device settings.

An empty values map does not imply that no device is installed: a device whose most recent observation predates its current installation produces no in-scope values yet still appears under device. To detect whether a location has a device, check the device object rather than values.

product-name is the human-readable product name (e.g. "Loop One", "Loop Delta") resolved server-side from the first two characters of device-type. It is null when the device’s type prefix is not in the product catalog (e.g. legacy or third-party devices).

Recipe: Coloring a current measurement value DRAFT

To color a last-quantities value the same way the Loopshore web UI does, combine the per-location override, the global defaults, and the user’s selected strictness tier. Fetch quantities-v2 and last-quantities with the same path. For each value, pick a curve in this priority order:

1. Per-location override. If quantities-v2.locations[<id>].location-thresholds[<quantity>].aqi-curve exists AND your user has “use location thresholds” enabled, use that single curve.
2. Tier-specific default. Otherwise, read quantities-v2.quantities[<quantity>].default-thresholds[<tier>], where <tier> is the user’s selected strictness ("S1+", "S2+", or "S3+").
3. Non-tiered default. If the quantity has no tiered curves (e.g., batt, rsrp), fall back to default-thresholds.default.
4. No curve available. If none of the above exist (e.g., pm10*, or lafmax where thresholds are unset), do not color the value — render it in a neutral style.

Once you have a curve, classify the measurement value against it using the classify algorithm under Analysis & Air Quality below, and map the result to the status colors in that section.

This is the same classification the web UI, the backend analysis engine, and the alarm system all use — it is not a continuous 0–5 score compared against a fixed cutoff like 3.5. (An earlier version of this recipe said to interpolate a continuous score and threshold it at 3.5/2.0; that was wrong and disagreed with every real implementation, including this API’s own analysis engine — do not use it.)

Note. Calling the classifier with an empty thresholds object silently returns “good” for every value, because the absence of any breakpoint causes all values to fall into the default classification. Always check that you found a non-null curve before classifying.

Analysis & Air Quality DRAFT

The analysis system evaluates air quality by comparing measurement data against threshold curves. It produces good/warn/alarm classifications and percentage breakdowns for each quantity at each location.

AQI curve format: An array of [measurement_value, quality_score] coordinate pairs that define a piecewise-linear mapping function. quality_score runs 0 (worst) to 5 (best) and exists only to define the curve’s shape — no endpoint returns it as a standalone number. Values between points are linearly interpolated; values outside the outermost points are clamped to the nearest endpoint score.

Example (temperature, S1+): [[15.0, 0.0], [20.0, 2.0], [20.5, 5.0], [25.0, 5.0], [27.0, 2.0], [32.0, 0.0]]

Reading: 15 °C → score 0 (bad), 20 °C → score 2 (alarm/warn boundary), 20.5–25 °C → score 5 (optimal plateau), 27 °C → score 2, 32 °C → score 0.

Classifying a value (good / warn / alarm): A curve author sets value breakpoints — alarm-low ≤ goal-low ≤ goal-high ≤ alarm-high (one-sided curves omit the low or high pair) — and those are, by construction, exactly the measurement_values where the curve’s score crosses 2 (alarm/warn boundary) and 5 (warn/good boundary). Classification recovers those breakpoints from the curve and buckets the value against them directly. It does not interpolate a continuous score and compare it to a fixed number like 3.5 — no such cutoff exists anywhere in the actual implementation:

function classify(curve, value):
  type = curveShape(curve)                       // 'raising' | 'declining' | 'hump' | 'pit'
  warnBounds = valuesWhereScoreEquals(curve, 2)   // 1 or 2 values, via reverse interpolation
  goodBounds = valuesWhereScoreEquals(curve, 5)   // 1 or 2 values, via reverse interpolation
  switch type:
    case 'raising':                    // bigger value = better
      if value < warnBounds[0]: return ALARM
      if value < goodBounds[0]: return WARN
      return GOOD
    case 'declining':                  // bigger value = worse
      if value > last(warnBounds): return ALARM
      if value > last(goodBounds): return WARN
      return GOOD
    case 'hump':                       // the common two-sided case: alarm-low/goal-low/goal-high/alarm-high
      if value < warnBounds[0] or value > warnBounds[1]: return ALARM
      if value < goodBounds[0] or value > goodBounds[1]: return WARN
      return GOOD
    case 'pit':                        // inverse of hump — good is outside, alarm is in the middle
      if value < goodBounds[0] or value > goodBounds[1]: return GOOD
      if value < warnBounds[0] or value > warnBounds[1]: return WARN
      return ALARM

curveShape looks at whether the score rises, falls, or reverses direction once as measurement_value increases across the curve’s points. hump is what a normal two-sided threshold (alarm-low/goal-low/goal-high/alarm-high) produces. This is the same algorithm the web UI and the backend analysis engine both use — for a curve built from typed-in breakpoints, it reproduces those exact breakpoints, because they are precisely where the curve was defined to cross score 2 and score 5.

Status colors:

Threshold modes:

For each quantity, the system can evaluate measurements against one or more AQI curves. Each curve is classified independently using the classify algorithm above, into the status colors in the table above.

• Finnish Classification of Indoor Environment (default). For indoor-air quantities (temperature, CO₂, humidity, PM2.5, TVOC, noise), the system defines three parallel strictness tiers: S1+ (individual / strictest), S2+ (good), S3+ (satisfactory / most lenient). These are three separate curves, not three bands within one curve. The analysis response contains a separate good/warn/alarm breakdown per tier under analyses[].thresholds.S1+, .S2+, and .S3+. Your client picks which tier to present.
• Particle counts. pn0p5 and pn1p0 have the same curve under S1+, S2+ and S3+, and no default.
• Non-tiered defaults. Quantities outside the Finnish standard (e.g., battery, signal strength) use a single curve under the default key.
• User-defined thresholds (identifier lt, “location threshold”). Custom AQI curves configured per location per quantity, overriding the default curves when present. Pass threshold=user on analysis requests to compute against these. In quantities-v2, they appear under locations.<id>.location-thresholds.<quantity>.aqi-curve.

Get analysis results DRAFT

Returns aggregated analysis results for locations under the given path. By default, returns the immediate children of the path. Use tag to filter to a specific level (e.g., tag=room returns all rooms under the path). Archived locations are excluded. A share link gets only the shared location: with tag, when it has that tag; without tag, an empty list.

Example response

[
  {
    "path": "campus.office.floor_1.room_101",
    "location": 15,
    "name": "Meeting Room",
    "analysis_in_progress": false,
    "analyses": [
      {
        "quantity": "temperature",
        "numeric": {
          "avg": {"value": 22.1},
          "min": {"value": 19.5, "dt": "2024-01-15T03:00:00Z"},
          "max": {"value": 24.8, "dt": "2024-01-15T14:30:00Z"}
        },
        "thresholds": {
          "S1+": {
            "total": {"percents": 100, "count": 144},
            "good": {"percents": 85, "count": 122},
            "warn": {"percents": 10, "count": 15},
            "alarm": {"percents": 5, "count": 7}
          }
        }
      },
      {
        "quantity": "co2",
        "numeric": {
          "avg": {"value": 580},
          "min": {"value": 410, "dt": "2024-01-15T06:00:00Z"},
          "max": {"value": 1150, "dt": "2024-01-15T13:00:00Z"}
        },
        "thresholds": {
          "S1+": {
            "total": {"percents": 100, "count": 144},
            "good": {"percents": 72, "count": 104},
            "warn": {"percents": 20, "count": 29},
            "alarm": {"percents": 8, "count": 11}
          }
        }
      }
    ]
  }
]

Response fields:

Alarms DRAFT

The alarm system monitors measurement data and sends notifications when values cross configured thresholds. Each user configures their own alarms — alarms are per-user, per-location, per-quantity.

Alarm configuration types:

Alarm lifecycle:

1. idle — Normal state, no alarm condition
2. pending — Threshold breached, waiting for delay minutes before activating
3. activated — Delay expired, notification sent. Alarm stays activated until the condition clears and hysteresis minutes pass
4. idle — Condition cleared, alarm resets

Quantity scope: location_threshold alarms work with any quantity the system tracks — both environmental measurements (temperature, humidity, co2, …) and device-health metrics (batt, rsrp, snr). For example, to alert when battery drops below a level, create a location_threshold alarm with quantity: "batt" and an appropriate threshold curve. See the quantities table for the full list.

Configuration parameters:

• delay (minutes): How long the threshold must be continuously breached before the alarm activates. Prevents false alarms from momentary spikes.
• hysteresis (minutes): After an alarm clears, how long to wait before the alarm can re-trigger. Prevents rapid on/off cycling.
• medium: Notification channels. [1] = email, [2] = SMS, [1, 2] = both, [] = no notifications.
• aqi-curve: The location’s threshold curve for the quantity. The curve is an array of [measurement_value, quality_score] pairs defining a piecewise-linear mapping — see AQI curve format in the Analysis & Air Quality section for full details (interpolation rules, clamping at endpoints, quality score range 0–5). A valid curve has at least two distinct points and crosses both score 2 (alarm limit) and score 5 (goal limit); see Building a curve from limits below.

The curve belongs to the location, not to one user’s alarm: there is one per location and quantity, shared by every user’s alarm on that quantity there and by the user-defined thresholds (lt) in analysis. Set or delete it with Set location threshold and Delete location threshold. When it changes, every alarm on that quantity at the location gets a threshold_update or threshold_deleted event and returns to idle, so it is evaluated again against the new curve.

Without a curve, threshold alarms don’t fire. The UI and analysis then rate measurements with the quantity’s default thresholds, but alarms have no default to fall back to: a location_threshold alarm on a measured quantity stays silent until someone sets the location’s curve.

Breach condition:

The alarm is considered breached when the aqi-curve score for the current measurement drops below 2.0. This is the same alarm/warn boundary the classify algorithm in Analysis & Air Quality uses (< 2.0 = Alarm). When designing a custom curve, make sure the region you want to alarm on maps to a score below 2, and the safe region maps to a score ≥ 2. See the upper-threshold example below.

Get alarm events DRAFT

Returns alarm events for the current user within the given time range. Maximum 5000 events, ordered by timestamp (newest first).

Only events of alarms at locations you can view now are returned. Alarms at archived locations, or at locations you no longer have access to, are left out; the alarm configurations are kept, and their events are returned again if access is restored.

Example response

[
  {
    "id": 1,
    "config-id": 42,
    "event-type": "activated",
    "timestamp": "2024-01-15T14:30:00Z",
    "reference-id": null,
    "event-text": null,
    "user-id": 1,
    "location-id": 15,
    "location-path": "campus.office.floor_1.room_101",
    "location-name": "Meeting Room",
    "quantity": "temperature",
    "config-type": "location_threshold"
  }
]

Event types:

Get alarm state DRAFT

Returns the current state of the alarms configured by the current user at locations you can view now. As with alarm events, alarms at archived locations or at locations you no longer have access to are left out.

Example response

[
  {
    "config-id": 42,
    "current-state": "idle",
    "enabled": true,
    "last-breached": null,
    "last-activated": null,
    "user-id": 1,
    "location-id": 15,
    "location-path": "campus.office.floor_1.room_101",
    "location-name": "Meeting Room",
    "quantity": "temperature",
    "config-type": "location_threshold"
  }
]

Get alarm configuration DRAFT

Get the current user’s alarm configuration for a specific location. Returns 404 if no alarm is configured.

Example response

{
  "delay-minutes": 30,
  "hysteresis-minutes": 15,
  "enabled": true,
  "medium": [1, 2],
  "aqi-curve": [[15.0, 0.0], [20.7, 5.0], [21.3, 5.0], [27.0, 0.0]],
  "config-type": "location_threshold",
  "default-thresholds": [[15.0, 0.0], [20.7, 5.0], [21.3, 5.0], [27.0, 0.0]]
}

Set alarm configuration DRAFT

Create or update an alarm configuration. Only location_threshold and location_no_data configs can be created through this endpoint; passing device_problem returns 400 "Invalid config type".

Required role: viewer or a wider tier at the location, or alarm-subscriber on a guest-viewer grant in another organization. Quantity alarms need more; see below. Not open to share links.

A threshold alarm on a measured quantity (location_threshold on any quantity except the system quantities batt, rsrp and snr) needs quantity alarm subscriptions at the location: org-admin, building-admin, or a tier with the alarm-subscriber add-on. Without it the request returns 403, except when it only switches off your own existing alarm (enabled false). The save never changes or deletes the location’s curve. Alarms about the device itself need only a tier from viewer up at the location, or alarm-subscriber on a guest-viewer grant in another organization: no-data alarms (location_no_data) and thresholds on batt, rsrp or snr.

Example request

{
  "delay": 30,
  "hysteresis": 15,
  "medium": [1, 2],
  "config-type": "location_threshold",
  "quantity": "temperature",
  "enabled": true
}

Example response

{
  "id": 42,
  "delay-minutes": 30,
  "hysteresis-minutes": 15,
  "enabled": true,
  "medium": [1, 2],
  "quantity": "temperature",
  "config-type": "location_threshold",
  "aqi-curve": [[15.0, 0.0], [20.7, 5.0], [21.3, 5.0], [27.0, 0.0]]
}

Note: the POST response does not include default-thresholds. Use the GET endpoint if you need to read the system default thresholds for a quantity.

Building a curve from limits

A threshold is usually described with up to four limits: alarm-low < goal-low ≤ goal-high < alarm-high. Each limit becomes one curve point, in ascending order of value:

Beyond each alarm limit, add one more point with score 0.0, so that values past the limit score below 2 and breach the alarm. Values between an alarm limit and its goal limit are classified as warn, and values between the goal limits as good.

Each alarm limit needs the goal limit on the same side: alarm-low with goal-low, alarm-high with goal-high. A one-sided threshold leaves out the pair on the other side.

Two-sided, temperature: alarm below 19 °C or above 26 °C, good from 20.5 °C to 23.5 °C:

"aqi-curve": [[18.0, 0.0], [19.0, 2.0], [20.5, 5.0], [23.5, 5.0], [26.0, 2.0], [27.0, 0.0]]

Upper side only, CO₂: alarm above 1200 ppm, good up to 750 ppm:

"aqi-curve": [[750.0, 5.0], [1200.0, 2.0], [1300.0, 0.0]]

Lower side only, battery: alarm below 20 %, good from 30 %:

"aqi-curve": [[10.0, 0.0], [20.0, 2.0], [30.0, 5.0]]

Example: upper-threshold alarm

Scenario: send an email when the temperature at a location stays above 23 °C for 45 minutes.

The default Finnish indoor thresholds are bell-shaped (too cold and too warm both count as breaches), so to alarm only on the upper side you supply a custom curve that drops below score 2 as soon as the value exceeds 23 °C:

{
  "delay": 45,
  "hysteresis": 0,
  "medium": [1],
  "config-type": "location_threshold",
  "quantity": "temperature",
  "aqi-curve": [[22.99, 5.0], [23.0, 2.0], [23.01, 0.0]]
}

How the curve works:

• At 22.99 °C and below, the score clamps to 5.0 → safe.
• At exactly 23.0 °C, the score is 2.0 → still safe (breach requires below 2).
• At 23.01 °C and above, the score clamps to 0.0 → breached.
• With delay: 45, the alarm must stay breached for 45 continuous minutes before activating and sending the email.
• With hysteresis: 0, the alarm can re-trigger as soon as the condition re-breaches after clearing.

The same pattern inverts for lower-threshold alarms (e.g. “below 18 °C”): put the low-score region on the left and the high-score region on the right.

Example: battery-low alarm

Scenario: send an email when battery at a location stays below 10 % for 60 minutes.

{
  "delay": 60,
  "hysteresis": 0,
  "medium": [1],
  "config-type": "location_threshold",
  "quantity": "batt",
  "aqi-curve": [[9.99, 0.0], [10.0, 2.0], [10.01, 5.0]]
}

How the curve works:

• At 9.99 % and below, the score clamps to 0.0 → breached.
• At exactly 10.0 %, the score is 2.0 → still safe (breach requires below 2).
• At 10.01 % and above, the score clamps to 5.0 → safe.

Caution — device-specific timing: Different device types have different battery lifetimes and measurement intervals. While the API allows free configuration of batt thresholds and location_no_data delays, it is recommended to use the system default values unless you have a specific reason to override. For example, setting a 30-minute location_no_data delay on a device that only reports once per hour will cause repeated false alarms. The system defaults are tuned per device type by the platform operator.

Validation rules:

• location_threshold requires quantity to be set
• location_no_data requires quantity to be null
• device_problem cannot be set via this endpoint
• For a measured quantity, aqi-curve null or left out keeps the location’s curve; only Delete location threshold removes it. Any other aqi-curve, also the curve already set, returns 400 {"error": "Bad Request", "message": "A quantity alarm's threshold is set through the location's threshold endpoint"}, and nothing is saved. For batt, rsrp and snr, null removes the curve
• For batt, rsrp and snr, aqi-curve must have at least two distinct points and cross both score 2 and score 5. Any other curve, such as an empty array, a single point, or a curve whose scores never reach 2 or 5, returns 400 {"error": "Bad Request", "message": "Invalid aqi-curve"}, and nothing is saved

Get location threshold DRAFT

The location’s threshold curve for a quantity, shared by every alarm on it there.

Required role: guest-viewer or a wider tier at the location, or a share link.

Example response

{
  "quantity": "co2",
  "aqi-curve": [[750.0, 5.0], [1200.0, 2.0], [1300.0, 0.0]],
  "default-thresholds": [[0.0, 5.0], [1050.0, 5.0], [1300.0, 0.0]],
  "subscribers": 3
}

Set location threshold DRAFT

Sets the location’s threshold curve for a quantity. When the curve changes, every alarm on that quantity at the location gets a threshold_update event and returns to idle, and the location’s analysis is recalculated. Sending the curve already set changes nothing.

Required role: alarm threshold editing at the location: org-admin, building-admin, or the threshold-editor add-on. Not open to share links.

The response is the same as Get location threshold.

Example request

{
  "quantity": "co2",
  "aqi-curve": [[750.0, 5.0], [1200.0, 2.0], [1300.0, 0.0]]
}

Rules: - The curve follows the rules in Building a curve from limits above; anything else returns 400 {"error": "Bad Request", "message": "Invalid aqi-curve"}, and nothing is saved - batt, rsrp and snr return 400: their curve is saved with the alarm itself (Set alarm configuration)

Delete location threshold DRAFT

Removes the location’s threshold curve for a quantity. Every alarm on that quantity at the location gets a threshold_deleted event, returns to idle, and doesn’t fire until a curve is set again; check subscribers in Get location threshold first. Deleting a curve that isn’t set changes nothing.

Required role: as for Set location threshold. batt, rsrp and snr return 400.

The response is the same as Get location threshold, with aqi-curve null.

Weather Data DRAFT

Weather data allows overlaying outdoor conditions (temperature, humidity, etc.) on indoor measurement graphs. Each location can be linked to a nearby weather station.

Search weather stations DRAFT

Search for weather stations by name.

Example response

{
  "stations": [
    {
      "id": 1,
      "name": "Helsinki-Vantaa lentoasema",
      "lat": 60.3172,
      "lon": 25.2458,
      "provider": "fmi",
      "external-id": "100953"
    }
  ]
}

Get weather observations DRAFT

Get weather observation data from a station within the given time range.

Set weather station for location DRAFT

Link a weather station to a location.

Required role: viewer or a wider tier at the location, or a read-write share link

Example request

{
  "station-id": 1
}

Remove weather station from location DRAFT

Remove the weather station link from a location. Returns 204 on success.

Required role: viewer or a wider tier at the location, or a read-write share link

Set weather display configuration DRAFT

Set display preferences for weather data at a location (e.g., which weather quantities to show on graphs).

Required role: viewer or a wider tier at the location, or a read-write share link

Location Customization DRAFT

These APIs allow users to customize how locations are displayed: images, floor plan coordinates, graph settings, and derived quantities.

Location images DRAFT

Locations can have two types of images: facade (building photo) and blueprint (floor plan). The image type is specified via the tag query parameter.

Required role: Reading: anyone who sees the location. Uploading and deleting: viewer or a wider tier at the location

Upload image

Upload as multipart form data. Maximum image size is 10 MB.

Example response

{
  "filename": "office_blueprint.png",
  "size": 2048576
}

Download image

Returns the image as binary data with appropriate Content-Type header.

Delete image

Returns 204 on success.

Discovering available images. The images field returned by GET location/tree/my-locations and GET location/{id} lists the tags that have been uploaded for each location (e.g., ["facade"], ["facade", "blueprint"], or [null] if none). Check this field before calling GET to avoid wasted 404 round-trips.

Blueprint coordinates DRAFT

Position rooms on floor plan images. See blueprint-coordinates in the Data (Node Metadata) section for the data format.

Required role: Reading: anyone who sees the location. Setting and deleting: viewer or a wider tier at the location

PUT request/response example:

[
  {
    "parent-location": 10,
    "coords": {"x": 450, "y": 280}
  }
]

Derived quantities DRAFT

Custom calculated quantities. See derived-quantities in the Data (Node Metadata) section for the concept.

Required role: Reading: anyone who sees the location. Creating, changing and deleting: viewer or a wider tier at the location

POST/PUT request example:

{
  "name": "Comfort Index",
  "source": "temperature"
}

Graph settings DRAFT

Per-quantity Y-axis configuration. See graph-settings in the Data (Node Metadata) section for the data format.

Required role: viewer or a wider tier at the location, or a read-write share link

PUT request example:

{
  "graph-settings": {
    "temperature": {"y-axis-min": 15.0, "y-axis-max": 30.0},
    "co2": {"y-axis-min": 400, "y-axis-max": 2000}
  }
}

Location Notes DRAFT

Notes are free-text annotations pinned to a location at a specific point in time. They can for example be surfaced as markers on the location measurements graph and are intended for human commentary that helps interpret the data later (e.g. “HVAC filter replaced”, “window left open during cleaning”, “tenant complaint about cold draft”).

Visibility model

Each note has a visibility of either "shared" or "private":

• shared — visible to anyone with access to the location. Anyone with location access can edit or delete the note.
• private — visible only to the author. Only the author can edit or delete the note.

To prevent a user from hiding their own work-in-progress notes from the team without consent (and the inverse), changing visibility into or out of private is restricted to the original author. A non-author can edit a shared note’s body but not flip it to private; nor can they promote someone else’s private note to shared.

Audit fields

Each note records who created it (created-by, created-by-name, created-at) and, once edited, who last edited it (updated-by, updated-by-name, updated-at). Deletion is a soft-delete server-side; deleted notes are not returned by the list endpoint.

Body length

The body field is required, must be non-blank, and is limited to 4000 characters.

List notes DRAFT

Returns all non-deleted notes for the location whose event-at falls within [from, to], filtered to those visible to the caller (all shared notes plus the caller’s own private notes). Ordered by event-at ascending.

Example response