Lenses¶
A lens is a named, aliased group of processor templates, owned by one organization. A subscription names a lens by its alias, and the lens decides how raw sensor data becomes the events that subscription receives. A lens is private, usable only by its own organization's subscriptions, or public, usable by any organization's subscriptions. See Subscriptions & Events for the concept.
Every call acts in one organization. A portal user names it with organizationId: a query parameter on GET and DELETE, a body field on POST and PUT. The caller must hold the permission shown in that organization. Lenses are most often managed in the Portal, which lets you pick member templates visually.
Endpoints¶
| Method | Path | Permission | Purpose |
|---|---|---|---|
GET |
/lenses |
lenses:read |
Your organization's lenses. The whole list by default; batched and searchable on request. |
POST |
/lenses |
lenses:write |
Create a lens; answers 201 with the lens. Creating it public also needs lenses:make_public. |
GET |
/lenses/{id} |
lenses:read |
One of your organization's lenses. |
PUT |
/lenses/{id} |
lenses:write |
Change a lens's name, alias, description, templates or visibility. Changing visibility also needs lenses:make_public. |
DELETE |
/lenses/{id} |
lenses:delete |
Delete a lens. Deleting a public lens also needs lenses:make_public. |
GET /lenses/{id}, PUT and DELETE act only on your own organization's lenses. Another organization's lens, public or not, answers 404, exactly like an unknown one.
What a lens carries¶
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"organizationId": "4f5e6d7c-8b9a-4c0d-9e1f-2a3b4c5d6e7f",
"name": "Traffic",
"alias": "traffic",
"description": "Vehicles and pedestrians at intersections",
"isPublic": true,
"processorTemplates": [
{ "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a", "organizationId": "4f5e6d7c-8b9a-4c0d-9e1f-2a3b4c5d6e7f", "name": "Person detector", "slug": "person-detector" },
{ "id": "0a1b2c3d-4e5f-4a6b-9c7d-8e9f0a1b2c3d", "organizationId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b", "name": "Vehicle counter", "slug": "vehicle-counter" }
],
"createdAt": "2026-01-10 00:00:00+00",
"updatedAt": "2026-01-12 00:00:00+00"
}
A public lens holding two public templates, one of them published by another organization. processorTemplates is ordered by template name.
Who may subscribe through a lens¶
- Your own organization's lens can be used by your subscriptions whether it is private or public.
- A public lens can be used by any organization's subscriptions. Name it by its alias in
POST /subscriptions. - Another organization's private lens is refused with
404 LENS_NOT_ACCESSIBLE, the same answer as an alias that does not exist. The platform does not reveal which of the two it was.
GET /lenses lists only your own organization's lenses. Another organization's public lenses are not listed, so to use one you need its alias. Aliases are unique across every organization, so an alias always names at most one lens.
Which templates a lens may hold¶
One rule decides every attachment: a template may join a lens if the template is public, or if the lens is a private lens of the template's own organization. In practice:
- A public lens holds only public templates. They can come from your organization or from any other.
- A private lens holds your organization's own templates, public or private, plus other organizations' public templates.
- A lens cannot be made public while it holds a private template. The request is refused with
422, and the error names the private templates. Removing them in the samePUTthat makes the lens public is accepted. - A template in a public lens, or in another organization's lens, cannot be made private until it has been removed from those lenses.
The platform's database enforces this rule as well, so there is no way around it.
A lens may hold several templates that produce the same event type; nothing refuses that. When a subscription is matched, the platform picks, for each sensor type, the smallest set of the lens's templates that covers the requested event types. Only templates with an approved, active version are considered. Other templates can sit in a lens, but no subscription will use them until one of their versions is approved.
Create a lens¶
POST /lenses
| Field | Required | Notes |
|---|---|---|
organizationId |
yes | The organization that will own the lens. |
name |
yes | Trimmed; may not be blank; at most 100 characters. |
alias |
yes | At most 100 characters: lowercase letters, digits, _ and -, starting and ending with a letter or digit. Unique across every organization. This is what subscriptions use. |
description |
no | Free text. |
processorTemplateIds |
no | Array of template ids to attach. Repeated ids are ignored. Each must be allowed by the rule above. |
isPublic |
no | Boolean; defaults to false. true needs lenses:make_public. |
Update a lens¶
PUT /lenses/{id} takes organizationId plus only the fields you want to change. At least one of name, alias, description, processorTemplateIds or isPublic must be sent.
processorTemplateIdsreplaces the whole set. Send every template the lens should hold. Any template you leave out is detached.- Only a real visibility change needs
lenses:make_public. SendingisPublicwith the value the lens already has is accepted without it. If the change is refused, nothing else in the request is applied either. nullor an empty string clearsdescription.- Renaming the alias does not break existing subscriptions. They are tied to the lens, not to its alias, and reading them shows the new alias. New subscribe requests must use the new alias.
Delete a lens¶
DELETE /lenses/{id} → 200 { "message": "Lens deleted", "id": "..." }
Deletion is permanent. Deleting a public lens needs lenses:make_public; without it, ask someone who holds that permission to delete it. Making the lens private first is no way around this: changing a lens's visibility needs the same permission. For what happens to subscriptions that were using the lens, see below.
Refusals¶
| Status | Code | When |
|---|---|---|
400 |
— | name or alias is missing (on create), blank or longer than 100 characters; alias has other characters; isPublic is not a boolean; processorTemplateIds is not an array of ids; the lens id or organizationId is not a UUID; or an update carries nothing to change. |
403 |
— | The caller lacks the permission for the route; or, without lenses:make_public, tries to create a public lens, change a lens's visibility, or delete a public lens. |
404 |
— | No such lens in your organization. |
409 |
ALIAS_TAKEN |
The alias is not available. The answer is the same whether your organization or another one holds it. |
422 |
— | processorTemplateIds names a template that does not exist, puts a private template in a public lens (including by making public a lens that holds one), or names another organization's private template. |
Branch on code, not on the sentence in error. See Errors and codes.
Listing lenses¶
GET /lenses has no page mode. With no extra parameters it returns the whole list at once, ordered by name:
It answers one batch instead as soon as the request carries any of limit, offset, cursor, search, ids or templateId. The batch comes with a pagination block beside count, and count is then the size of that batch. Batches follow the rules in Lists: page mode and batch mode, including 400 CURSOR_MISMATCH for a cursor that does not belong to the request.
| Parameter | Meaning |
|---|---|
search |
Keeps lenses whose name or alias contains the text, ignoring case. |
ids |
Comma-separated list of up to 100 lens ids. Narrows the list to those lenses and never widens it beyond your organization. A value that is not a UUID, or more than 100, answers 400. |
templateId |
Keeps only the lenses that hold this template. A value that is not a UUID answers 400. |
sortBy |
name (the default, A to Z) or createdAt (the default is newest first). Both can be continued with nextCursor. |
sortDirection |
asc or desc. |
When a lens changes under running subscriptions¶
A lens can be edited, made private or deleted at any time, even while subscriptions use it; none of these changes is refused. Subscriptions are tied to the lens itself. Every hour the platform re-checks each active subscription whose lens still exists against the lens as it now stands, and sends an updated control message when the subscription's coverage changed. See how coverage changes.
| Change to the lens | What subscriptions using it see |
|---|---|
| A template is attached or detached | At the next re-check the subscription is matched again against the lens's current templates. A newly attached template can then be picked and its processors started or reused; a detached template's processors are released. |
| The alias is renamed | Nothing changes. Reads show the new alias; new subscribe requests must use it. |
| It is made public | Other organizations can subscribe through it straight away. |
| It is made private | Your own organization's subscriptions are unaffected. Another organization's subscriptions stay active, but at the next re-check every event type becomes uncovered with the reason LENS_NOT_ACCESSIBLE and delivery stops. They recover by themselves at the first re-check after the lens is public again. |
| It is deleted | Every subscription using it stays active, and its lensAlias reads null from then on. The hourly re-check skips it after that, so its coverage report is no longer updated and nothing is matched for it again. This does not recover: a new lens with the same alias is not connected to it. A subscription cannot be pointed at another lens, so delete it and subscribe again. |