Sensors & Tags¶
Catalog endpoints for the two things subscriptions build on: sensors (the devices that produce data) and tags (the event-type vocabulary). Each organization registers its own. A sensor its owner makes public can also serve other organizations' subscriptions, and the tags of every organization together are the event types anyone can subscribe to.
Every call names the organization it acts in — organizationId as a query parameter on GET and DELETE, as a body field on POST and PUT — and the caller must hold the permission shown in that organization.
Sensors¶
A sensor is a registered device with a type, a location (its pin on the map) and an area of view — the ground it watches. Subscriptions match sensors by their area of view, not by the pin; see Subscriptions & Events.
| Method | Path | Permission | Purpose |
|---|---|---|---|
GET |
/sensors |
sensors:read |
List sensors — your organization's by default, or other organizations' public ones. Paged or batched, searchable, sortable. |
GET |
/sensors/active |
sensors:read |
Every active sensor of your own organization, oldest first, in one response. |
GET |
/sensors/types |
sensors:read |
The sensor types: camera, lidar, radar, rf_sensor, fused. |
POST |
/sensors |
sensors:write |
Register a sensor; answers 201 with the sensor. |
GET |
/sensors/{id} |
sensors:read |
One of your organization's sensors. |
PUT |
/sensors/{id} |
sensors:write |
Change a sensor, including whether it is public and its device login. |
DELETE |
/sensors/{id} |
sensors:delete |
Decommission a sensor. |
Which sensors a list covers¶
GET /sensors takes a scope query parameter:
scope |
Rows |
|---|---|
own (default) |
Your organization's sensors. |
public |
Sensors other organizations have made public. Never your own, not even your public ones. |
all |
Both of the above. Its total is the own total plus the public total. |
A missing or unrecognized scope means own. Decommissioned sensors are never listed, whatever the scope; inactive ones are.
GET /sensors/{id}, PUT and DELETE act only on your own organization's sensors. Another organization's sensor, public or not, answers 404, exactly like an unknown or decommissioned one. Another organization's public sensor reaches you only as a row of GET /sensors under scope=public or scope=all.
What a sensor read carries¶
Every sensor read names the owning organization in organizationName and organizationSlug. That covers list rows in every scope, a single sensor, the active list, and the responses to create and update. Another organization's public sensor is named too: publishing a sensor tells other organizations whose device it is.
Your own rows also carry hasCredentials: true when a device login is saved for the sensor, false when none is. It is the only trace of a login that any read carries. No call returns the username or the password, to anyone, including your own organization.
{
"id": "5c2d8e1f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"organizationId": "8a9b0c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d",
"organizationName": "Acme City",
"organizationSlug": "acme",
"name": "Main St & 5th",
"description": "Northbound, pole-mounted",
"sensorType": "camera",
"locationLat": 26.705,
"locationLng": -80.051,
"coverageGeom": { "type": "Polygon", "coordinates": [[[-80.052, 26.704], [-80.050, 26.704], [-80.050, 26.706], [-80.052, 26.706], [-80.052, 26.704]]] },
"connectionConfig": { "stream_url": "rtsp://camera.example:554/stream", "fps": 5 },
"hasCredentials": true,
"metadata": { "mount": "pole" },
"isActive": true,
"isPublic": false,
"lastSeenAt": "2026-09-18 09:12:44+00",
"createdAt": "2026-09-01 14:03:10+00",
"updatedAt": "2026-09-18 08:55:02+00",
"decommissionedAt": null
}
One of your own sensors: the camera's address is in connectionConfig, and its login is not. hasCredentials says one is saved.
A read never returns a login inside connectionConfig either: keys that name a credential are left out of it, and a login written into a URL (user:pass@) is removed.
Publishing does not tell other organizations how to reach the device. On a row owned by another organization, connectionConfig and metadata are always empty objects and hasCredentials is absent, so nothing says whether the device needs a login.
{
"id": "0b7e4c1a-2d3f-4e5a-8b6c-7d8e9f0a1b2c",
"organizationId": "4f5e6d7c-8b9a-4c0d-9e1f-2a3b4c5d6e7f",
"organizationName": "Beta Labs",
"organizationSlug": "beta",
"name": "Beta Camera",
"description": null,
"sensorType": "camera",
"locationLat": 26.71,
"locationLng": -80.06,
"coverageGeom": { "type": "Polygon", "coordinates": [[[-80.061, 26.709], [-80.059, 26.709], [-80.059, 26.711], [-80.061, 26.711], [-80.061, 26.709]]] },
"connectionConfig": {},
"metadata": {},
"isActive": true,
"isPublic": true,
"lastSeenAt": null,
"createdAt": "2026-01-10 00:00:00+00",
"updatedAt": "2026-01-10 00:00:00+00",
"decommissionedAt": null
}
Another organization's public sensor, as a scope=all row: its owner is named, its connection details and metadata are empty, and it has no hasCredentials.
GET /sensors answers { "organizationId", "sensors": [...], "pagination" }; GET /sensors/active answers { "sensors": [...] }.
Public sensors and other organizations' subscriptions¶
A sensor is private unless isPublic is true. A private sensor serves only its own organization's subscriptions. A public sensor can serve any organization's subscription whose regions overlap its area of view. That subscriber receives the sensor's events; its coverage report counts the sensor but never names or locates it, and the sensor's connection details, its metadata and whether it has a device login are never shown to another organization. Making a sensor public needs no permission beyond sensors:write.
Subscriptions match only sensors that are active and not decommissioned. Setting isActive to false also takes a sensor out of matching. Publishing, unpublishing, changing the area of view, deactivating and decommissioning all reach existing subscriptions at their next hourly re-check. See Subscriptions: how coverage changes.
Register a sensor¶
POST /sensors
| Field | Required | Notes |
|---|---|---|
organizationId |
yes | The organization that will own the sensor. |
name |
yes | Trimmed; may not be blank. |
locationLat, locationLng |
yes | Numbers: latitude −90 to 90, longitude −180 to 180. |
sensorType |
no | One of the sensor types; defaults to camera. Any other value answers 400 with the code INVALID_REQUEST. |
coverageGeom |
no | The area of view, as a GeoJSON geometry such as a Polygon. Without it, the area of view is just the location point. |
description |
no | Free text. |
connectionConfig |
no | A JSON object saying how the platform reaches the device, such as its stream URL. Shown only to your own organization. Default {}. It must not hold a login: see What connectionConfig may hold. |
credentials |
no | The device login, as { "username": "…", "password": "…" }. Write-only: it is saved and never returned. Leave it out, or send null, for a device that needs no login. See Device logins. |
metadata |
no | A JSON object, shown only to your own organization. Default {}. |
isActive |
no | Defaults to true. |
isPublic |
no | Defaults to false. |
lastSeenAt |
no | A timestamp. |
A camera that needs a login:
{
"organizationId": "8a9b0c1d-2e3f-4a5b-8c6d-7e8f9a0b1c2d",
"name": "Main St & 5th",
"sensorType": "camera",
"locationLat": 26.705,
"locationLng": -80.051,
"connectionConfig": { "stream_url": "rtsp://camera.example:554/stream", "fps": 5 },
"credentials": { "username": "viewer", "password": "your-camera-password" }
}
The 201 response is the new sensor with "hasCredentials": true, and without the login.
Update a sensor¶
PUT /sensors/{id} takes organizationId plus only the fields you want to change; every field you leave out stays as it is.
- Location is both coordinates or neither. Sending one without the other answers
400. - Moving the pin does not move the area of view. New coordinates change the location only; the area of view changes only when you send a new
coverageGeom. nullresets the JSON fields. An explicitnullforconnectionConfigormetadataresets it to{}.- A new
connectionConfigreplaces the old one. The object you send is stored as it is, not merged into the saved one. - Leave
credentialsout to keep the login. An object replaces the saved login, andnullremoves it. ResettingconnectionConfignever touches the login. namemay not be blank.
Device logins¶
Some devices ask for a username and password before they share their stream. Send that login as credentials, never inside connectionConfig.
- A login is write-only. It is kept in a secure secret store, not in the sensor record, and no call returns it. Reads carry only
hasCredentials. To change a login you send the whole new one. - The platform uses it on your behalf. Processors never receive the login. For a camera, the platform signs in to the device itself, and starts using a new login within about 2 minutes. Any sensor type can hold a login, but today the platform signs in only to cameras.
- Replacing or removing a login changes this sensor only.
- Changing a device's password takes two steps. Change it on the device first, then send the new login with
PUT. The platform can't sign in to the device between the two steps, so processors may briefly lose its stream. - Decommissioning a sensor also removes its login.
- A camera's login needs a usable stream URL. A login can't be added to a camera whose saved
stream_urlorcamera_urlisn't usable. See WhatconnectionConfigmay hold.
credentials must be an object with exactly two keys:
| Key | Rules |
|---|---|
username |
A non-empty string of at most 256 characters, with no control characters (such as tabs or line breaks), no invalid characters and no colon (:). |
password |
A non-empty string of at most 256 characters, with no control characters and no invalid characters. |
An invalid character is half of a surrogate pair on its own, such as the JSON escape \ud800 with no partner after it. It is not a real character, and no device login contains one.
Both are saved exactly as you send them: nothing is trimmed or changed. A credentials value that is not such an object, has any other key or breaks one of these rules answers 400 with the code INVALID_CREDENTIALS. The error sentence names the problem, such as "A username can't contain a colon (:).", and never repeats what you sent.
Every other check runs before the login is saved, so a refused request saves nothing. If the login itself can't be saved, the request answers 502 with the code CREDENTIAL_STORE_UNAVAILABLE, and nothing about the sensor changes. Try again in a minute.
What connectionConfig may hold¶
connectionConfig says where and how the platform reaches the device. For a camera, put the address of its stream in stream_url, without a login. On create and update alike:
- It is a JSON object. Anything else answers
400with the codeINVALID_REQUEST. An explicitnullmeans{}. - It nests at most 32 levels deep. The top-level object is level 1. Deeper answers
400with the codeINVALID_REQUEST. -
It holds no login, at any depth. Either of these answers
400with the codeCREDENTIALS_IN_CONNECTION_CONFIG:- A key that names a credential: one ending in
user,username,password,passwd,pwd,secret,token,credential,credentials,apikey,accesskeyorprivatekey(the last three also with_or-beforekey), in any letter case. Soauth.user,client_secretandaccess_tokenare refused, whiletokenizeranduser_agentare allowed. - A URL with a login written into it:
scheme://anywhere in a string, followed by an@before the next/or whitespace, such asrtsp://admin:1234@camera.example/stream. An@in a query or fragment with no/before it (rtsp://camera.example?to=a@b) counts too, so percent-encode it as%40. A string that starts withscheme://also counts when it has an@anywhere before its first/,?or#, spaces included, such asrtsp://admin:my pass@camera.example/stream.
The
errorsentence names where it found the login, as a key path such asauth.userorstreams[0].url, and never the value. Remove it and send the login ascredentials. - A key that names a credential: one ending in
-
stream_urlandcamera_urlare usable URLs. When either is present at the top level, it must be a string that:- holds printable ASCII characters only: no spaces, tabs, line breaks or other control characters, and no characters outside ASCII. Write an international host name in its
xn--form, and percent-encode anything else. - holds no backslash (
\). - does not end in a colon (
:), even one followed only by?or#. - reads as a URL with a host. The host can't be an IPv6 address such as
[2001:db8::1], and a port, if given, must be from 1 to 65535.
Otherwise the request answers
400with the codeINVALID_STREAM_URL. This applies to every sensor type. - holds printable ASCII characters only: no spaces, tabs, line breaks or other control characters, and no characters outside ASCII. Write an international host name in its
-
A camera with a login must have a usable saved URL. An update that leaves a camera with a device login also checks the
stream_urlandcamera_urlalready saved in itsconnectionConfig, by the same rule, even when the request doesn't sendconnectionConfig: for example, an update that only adds a login, or only changessensorTypetocamera. If the saved URL fails, the update answers400with the codeINVALID_STREAM_URLand changes nothing, so a login can't be added to a camera whose saved stream URL is unusable. Fix the URL first, or send the correctedconnectionConfigin the same request.
Refusals on create and update¶
| Status | Code | When |
|---|---|---|
400 |
— | organizationId is missing or not a UUID; on update, the sensor id in the path is not a UUID; on create, name or the coordinates are missing; on either route, name is sent blank, or the coordinates are not numbers or are out of range; or, on update, one coordinate is sent without the other. |
400 |
INVALID_REQUEST |
sensorType is not one of the sensor types, or connectionConfig is not a JSON object or nests more than 32 levels deep. |
400 |
CREDENTIALS_IN_CONNECTION_CONFIG |
connectionConfig holds a login, as a credential key or inside a URL. |
400 |
INVALID_STREAM_URL |
stream_url or camera_url in connectionConfig is not a usable URL; or, on update, the sensor would be a camera with a device login whose saved URL isn't usable. |
400 |
INVALID_CREDENTIALS |
credentials is not a valid login. |
404 |
— | On update: no such sensor in your organization, or it has been decommissioned. |
502 |
CREDENTIAL_STORE_UNAVAILABLE |
The device login couldn't be saved. Nothing was changed; try again in a minute. |
Branch on code, not on the sentence in error.
Decommission a sensor¶
DELETE /sensors/{id} → 200 { "message": "Sensor decommissioned", "id": "..." }
Decommissioning is a soft delete. The sensor is marked inactive and decommissioned, its device login is removed, and from then on it is absent from every list and read on this page and is never matched again. No call brings it back. Subscriptions it was serving lose it at their next hourly re-check.
Tags¶
A tag is one entry in the event-type vocabulary. Its slug is the event type a subscription requests (for example person). A tag belongs to one organization and can sit under a parent tag of the same organization. The event types anyone may subscribe to are the slugs of every organization's tags together, which is what GET /metadata lists.
| Method | Path | Permission | Purpose |
|---|---|---|---|
GET |
/tags |
tags:read |
Your organization's tags. Paged or batched, searchable, sortable. |
GET |
/tags/all |
tags:read |
Every organization's tags — the platform-wide vocabulary — each row naming its owner. organizationId must name an organization you belong to, but the list is not limited to it. |
GET |
/tags/types |
tags:read |
The tag categories: object, activity. |
POST |
/tags |
tags:write |
Create a tag; answers 201 with the tag. |
GET |
/tags/{id} |
tags:read |
One of your organization's tags. |
PUT |
/tags/{id} |
tags:write |
Update a tag. |
DELETE |
/tags/{id} |
tags:delete |
Delete a tag. |
A tag carries id, organizationId, name, slug, description, parentId, parentName, parentSlug, createdAt and tagType; the 201 from create omits parentName and parentSlug. Rows of GET /tags/all add organizationName and organizationSlug, which are null if the owning organization has since been deleted. GET /tags answers { "organizationId", "tags": [...], "pagination" } and GET /tags/all answers { "tags": [...], "pagination" }.
Create or update a tag¶
| Field | Required on create | Notes |
|---|---|---|
organizationId |
yes (update too) | The organization that owns the tag. |
name |
yes | At most 100 characters; may not be blank. |
slug |
yes | At most 100 characters; unique within the organization. This is the event type. |
description |
no | Free text. |
parentId |
no | A tag in the same organization, or null for a top-level tag. |
tagType |
no | object (the default) or activity. |
On PUT /tags/{id}, send only the fields you want to change; "parentId": null moves the tag to the top level.
| Status | Code | When |
|---|---|---|
400 |
— | name or slug is missing (on create), blank or longer than 100 characters; parentId is not a UUID; or tagType is not one of the categories. |
400 |
— | parentId names no tag in your organization, names the tag itself, or would create a loop (the proposed parent sits beneath this tag). |
404 |
— | On update: no such tag in your organization. |
409 |
SLUG_TAKEN |
Another tag in the organization already has this slug. |
Branch on code, not on the sentence in error.
Deleting a tag keeps its child tags: they become top-level tags.
Narrowing a tag list¶
excludeSubtreeOf=<tagId>(GET /tagsonly) leaves out that tag and every tag beneath it — what a parent picker needs, so a tag is never offered one of its own descendants. An id from another organization excludes nothing; a value that is not a UUID answers400.ids=<id>,<id>,…(GET /tagsandGET /tags/all) keeps only those tags, up to 100, within what the route would list anyway. It narrows and never widens. A value that is not a UUID, or more than 100, answers400.
Paging through a list¶
GET /sensors, GET /tags and GET /tags/all share these query parameters:
| Parameter | Meaning |
|---|---|
search |
Free text matched against the rows' fields. For sensors, those are the ID, name, description, type, coordinates and last-seen time of every row, plus metadata on your own organization's rows only. connectionConfig is never searched, and neither is another organization's metadata. |
sortBy |
Sensors: createdAt, name, sensorType, isActive, isPublic, lastSeenAt, updatedAt. Tags: createdAt, name, id, slug, description, parentId, parentName, tagType. An unknown value means createdAt. Rows without a value sort last in either direction. |
sortDirection |
asc or desc (the default). |
Each list answers in one of two modes.
Page mode is the default: page and pageSize (default 20, at most 100). pagination is { "page", "pageSize", "totalCount", "totalPages" }, counted on every call.
Batch mode starts as soon as you send limit, offset or cursor; page and pageSize are then ignored. limit is 1 to 100 rows (default 50). pagination is { "limit", "offset", "totalCount", "hasMore", "nextCursor" }:
totalCountis a number on the first batch only (nocursor,offset0) andnullon every later one.hasMoresays whether more rows exist. Stop when it isfalse.nextCursoris set when more rows exist and the sort is on a value that never changes:createdAtornamefor sensors,createdAt,nameoridfor tags. Send it back ascursorwith the same sort, search,scopeand filters.- When
hasMoreistruebutnextCursorisnull, continue withoffsetset to the number of rows you already have.
A cursor that is malformed, was issued under a different sort, direction, search, scope or filter, is combined with an offset above 0, or is sent for a sort that continues by offset answers 400 with the code CURSOR_MISMATCH.
Note
The permission names above are portal permissions. A consumer app client's default credential carries no sensor or tag scopes: consumer integrations read the valid event types from GET /metadata and subscribe. Sensors and tags are usually managed in the Portal.