Skip to content

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.
  • null resets the JSON fields. An explicit null for connectionConfig or metadata resets it to {}.
  • A new connectionConfig replaces the old one. The object you send is stored as it is, not merged into the saved one.
  • Leave credentials out to keep the login. An object replaces the saved login, and null removes it. Resetting connectionConfig never touches the login.
  • name may 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_url or camera_url isn't usable. See What connectionConfig may 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 400 with the code INVALID_REQUEST. An explicit null means {}.
  • It nests at most 32 levels deep. The top-level object is level 1. Deeper answers 400 with the code INVALID_REQUEST.
  • It holds no login, at any depth. Either of these answers 400 with the code CREDENTIALS_IN_CONNECTION_CONFIG:

    • A key that names a credential: one ending in user, username, password, passwd, pwd, secret, token, credential, credentials, apikey, accesskey or privatekey (the last three also with _ or - before key), in any letter case. So auth.user, client_secret and access_token are refused, while tokenizer and user_agent are allowed.
    • A URL with a login written into it: scheme:// anywhere in a string, followed by an @ before the next / or whitespace, such as rtsp://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 with scheme:// also counts when it has an @ anywhere before its first /, ? or #, spaces included, such as rtsp://admin:my pass@camera.example/stream.

    The error sentence names where it found the login, as a key path such as auth.user or streams[0].url, and never the value. Remove it and send the login as credentials.

  • stream_url and camera_url are 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 400 with the code INVALID_STREAM_URL. This applies to every sensor type.

  • 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_url and camera_url already saved in its connectionConfig, by the same rule, even when the request doesn't send connectionConfig: for example, an update that only adds a login, or only changes sensorType to camera. If the saved URL fails, the update answers 400 with the code INVALID_STREAM_URL and 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 corrected connectionConfig in 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 /tags only) 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 answers 400.
  • ids=<id>,<id>,… (GET /tags and GET /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, answers 400.

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" }:

  • totalCount is a number on the first batch only (no cursor, offset 0) and null on every later one.
  • hasMore says whether more rows exist. Stop when it is false.
  • nextCursor is set when more rows exist and the sort is on a value that never changes: createdAt or name for sensors, createdAt, name or id for tags. Send it back as cursor with the same sort, search, scope and filters.
  • When hasMore is true but nextCursor is null, continue with offset set 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.