Loopshore API

Version 0.35.1

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 is only allowed to access the resources that are configured to the user by system admins. If you are trying to access a resource that you have not access to, 401 error code will be returned. Contact 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.

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:

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 or expired:

{"error": "Unauthorized", "message": "Authentication required"}

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"

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 and retry once
• 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.

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...

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.

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.

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”.

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
}]

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. 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",
  "nodes": [5, 12, 47],
  "profile": {
    "privileges": ["alarm-editor"]
  },
  "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"
}

Response fields:

Admins and superadmins additionally receive last-device-info (the device_info string from the most recent mobile session). It is stripped from this endpoint for regular users; see the admin user endpoints for the full shape.

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 unit preferences. All fields are optional — only include fields you want to change. Settings are synced across web and mobile.

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 admin-initiated reset emails 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.

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.

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.

Both users and admins receive data only for devices and time windows they have access to. 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 only for admin/superadmin callers, 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.
• 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).

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: Custom threshold curve for the quantity. If null, uses system default thresholds. 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).

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).

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 all alarms configured by the current user.

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

Example request

{
  "delay": 30,
  "hysteresis": 15,
  "medium": [1, 2],
  "config-type": "location_threshold",
  "quantity": "temperature",
  "aqi-curve": [[15.0, 0.0], [20.7, 5.0], [21.3, 5.0], [27.0, 0.0]],
  "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.

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
• Setting aqi-curve to null removes the custom curve and reverts to system defaults

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.

Example request

{
  "station-id": 1
}

Remove weather station from location DRAFT

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

Set weather display configuration DRAFT

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

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.

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.

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.

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.

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

[
  {
    "id": 42,
    "location-id": 1234,
    "event-at": "2026-04-15T08:30:00Z",
    "body": "HVAC filter replaced.",
    "visibility": "shared",
    "created-at": "2026-04-15T08:31:12Z",
    "created-by": 17,
    "created-by-name": "Maija Mehiläinen",
    "updated-at": "2026-04-15T08:35:02Z",
    "updated-by": 17,
    "updated-by-name": "Maija Mehiläinen"
  },
  {
    "id": 43,
    "location-id": 1234,
    "event-at": "2026-04-16T12:00:00Z",
    "body": "Tenant reported cold draft near window 3.",
    "visibility": "shared",
    "created-at": "2026-04-16T12:01:30Z",
    "created-by": 21,
    "created-by-name": "Pekka Pörhönen",
    "updated-at": null,
    "updated-by": null,
    "updated-by-name": null
  }
]

updated-at, updated-by, and updated-by-name are null until the note is edited.

Create note DRAFT

Request body

Example request

{
  "event-at": "2026-04-15T08:30:00Z",
  "body": "HVAC filter replaced.",
  "visibility": "shared"
}

Returns 201 Created with the created note record (same shape as the list response element).

Update note DRAFT

Request body

Returns 200 OK with the updated note record. The server sets updated-at, updated-by, and updated-by-name automatically.

Authorisation

• 404 Not Found if the note does not exist, has been deleted, or belongs to a different location than the path.
• 403 Forbidden if the note is currently private and the caller is not the author.
• 403 Forbidden if the request would change visibility into or out of private and the caller is not the author.
• Otherwise any user with access to the location may update the note.

Delete note DRAFT

Soft-deletes the note. Returns 204 No Content. The note will no longer be returned by the list endpoint after deletion.

Authorisation

• 404 Not Found if the note does not exist, is already deleted, or belongs to a different location than the path.
• 403 Forbidden if the note is private and the caller is not the author.
• Otherwise any user with access to the location may delete the note.

Surveys (Anonymous Access) DRAFT

Surveys are paged feedback questionnaires that can be answered anonymously. Each survey has multiple pages, and each page contains questions that are either multiple-choice or free-text.

These endpoints are public — no authentication required. Survey locations are identified by a hash ID (not the numeric location ID) to prevent enumeration.

Get survey DRAFT

Returns the survey structure and location breadcrumb.

Example response

{
  "survey": [
    {
      "title": {"en": "Indoor Air Quality Feedback", "fi": "Sisäilmapalaute"},
      "questions": [
        {
          "question-type": "choice",
          "question-text": {"en": "How is the temperature?", "fi": "Miten koet lämpötilan?"},
          "choices": [
            {"choice-text": {"en": "Too cold", "fi": "Liian kylmä"}, "quality": 1},
            {"choice-text": {"en": "Good", "fi": "Hyvä"}, "quality": 5},
            {"choice-text": {"en": "Too warm", "fi": "Liian lämmin"}, "quality": 1}
          ]
        },
        {
          "question-type": "free",
          "question-text": {"en": "Other feedback?", "fi": "Muuta palautetta?"}
        }
      ]
    }
  ],
  "location": [
    {"name": "Office Building", "tag": "building"},
    {"name": "Meeting Room", "tag": "room"}
  ]
}

Question types:

• choice — Multiple choice with a quality score (0–5) per option
• free — Free-form text input

Submit survey response DRAFT

Submit answers to a survey. Response keys are question indices (integers). Each response is either a choice response or a text response.

Example request

{
  "responses": {
    "0": {"choice-response": 1},
    "1": {"text-response": "The AC is too loud"}
  }
}

Returns 200 on success.

Internationalization DRAFT

Get translations DRAFT

Returns the UI translation strings for the given language as a nested JSON object. Authentication is optional — unauthenticated users get system default translations.

Example response

{
  "en": {
    "ui": {
      "dashboard": {
        "title": "Dashboard",
        "no-data": "No data available"
      }
    }
  }
}

Short URLs DRAFT

Create short URL DRAFT

Create a short URL for sharing. The short URL redirects to the target URL when visited.

Example request

{
  "type": "share",
  "target-url": "https://app.loopshore.com/share/view?path=campus.office"
}

Example response

{
  "id": 1,
  "code": "aBcDeFgH",
  "type": "share",
  "target-url": "https://app.loopshore.com/share/view?path=campus.office",
  "created-at": "2024-06-01T10:30:00Z",
  "visit-count": 0
}

The short URL is accessible at https://service.loopshore.com/s/{code}.

Admin APIs DRAFT

These APIs require admin role and are used for managing users, devices, and locations. Admin users can only manage resources within their assigned scope.

Scope and Permissions:

Admin users are restricted to their assigned group. This means:

• Users: Can only see and manage users in the same group
• Locations: Can only access locations assigned to their user account
• Devices: Can only manage devices at accessible locations
• Theme: Can only use themes assigned to their group

When trying to access resources outside their scope, the API returns 403 (Forbidden) or 404 (Not Found) — the API does not reveal whether a resource exists if you don’t have access to it.

Admin API Authentication

Admin APIs use the same authentication methods as User APIs:

• Session cookie: Set by the Login endpoint
• API key: Pass via x-api-key header

Key Concepts

Nodes (Location Access)

The nodes field is an array of location IDs that determine which parts of the location tree a user can access. Locations are organized hierarchically (building → floor → room), and each location has a numeric ID.

"nodes": [5, 12, 47]