API Overview¶
The Dory REST API is the control-plane interface used by the Web Portal and by programs that integrate directly. The Application SDK wraps the subscription and metadata endpoints and also handles the delivery queue and the platform's status messages for you — if you only need to consume events, prefer the SDK.
This section documents the externally relevant endpoints. Platform-internal and administrative endpoints are intentionally omitted.
Base URL & versioning¶
The version prefix (/v1) is part of the path. All examples below are relative to this base URL.
Authentication¶
Every endpoint (except GET /hello) requires a bearer token:
There are two kinds of caller — portal users (authorized by role-based permissions) and machine-to-machine app clients (authorized by OAuth scopes). See Authentication and the platform model in Identity & Access.
Conventions¶
- Format. Requests and responses are JSON (
Content-Type: application/json). - Organization scope. Every call acts within one organization. For an app client that is the organization the credential belongs to. A portal user names it —
organizationIdas a query parameter on list routes, or an{orgId}path segment on administrative routes. Routes addressed by a resource id (/subscriptions/{id}) act in the organization that owns that resource; a resource in another organization answers exactly like a missing one (404). - Ownership. M2M scopes ending in
:selfrestrict a client to the resources it created;:allcovers the whole organization. On routes addressed by an id, a:selfcredential that reaches a subscription created by another credential in the same organization gets403; a subscription in another organization gets404. - Lists. Paged list endpoints answer in two shapes: page mode (
page,pageSize) and batch mode (limit,offset,cursor), each with its ownpaginationblock. See Lists: page mode and batch mode. - Errors. Failures the API answers return a non-2xx status with
{ "error": "<message>" }, plus a stable"code"where one applies; a missing or invalid token is refused before the request reaches the API. See Errors and codes. - Accepted, then finished in the background. Creating and deleting a subscription answer
202 Accepted; they are the only endpoints that do. Inside the request the platform records the subscription and creates its delivery queue (or, on delete, removes the queue so delivery stops immediately); a worker then finishes the slow part — matching sensors, starting or releasing processors, binding the queue. A new subscription ispendinguntil that completes, thenactive(its coverage report may be empty — matching nothing is not an error); a deleted one reportsdeleting; one that could not be set up reportserror, with its reason code inlastErrorCode— delete it and subscribe again. Learn the outcome either from the control message the worker drops into the delivery queue (ready, laterupdatedwhenever coverage changes, orerrorwhen the worker gives up — the SDK handles these and never passes them to your event handler) or by readingGET /subscriptions/{id}, which returnsstatus, the coverage report,lastErrorCodeandactivatedAt. Not everyerroris announced on the queue, so the read is the one to trust. A202means the subscription exists: do not resubmit the same request, it would create a second one. The Subscriptions page has the full status table. - Not found vs. not yours.
404means the resource does not exist or is not accessible to your organization — an unknown lens alias and another organization's private lens get the same answer, and so do a missing subscription and one owned by another organization. A caller that reaches its own organization's resource but lacks the permission or the ownership reach gets403.
How an accepted request finishes¶
sequenceDiagram
autonumber
participant App as Your application
participant API as Dory API
participant Q as Delivery queue
participant W as Provisioning worker
App->>API: POST /subscriptions {eventTypes, geohashes, lensAlias}
API->>Q: create the delivery queue
API->>W: provision request
API-->>App: 202 Accepted {subscriptionId, queueName, status: "pending"}
Note over App,Q: You may start consuming the queue now
W->>W: match sensors · start or reuse processors · bind the queue
W->>Q: control message "ready" {coverage}
Q-->>App: handled by the SDK, never passed to your event handler
App->>API: GET /subscriptions/{id}
API-->>App: 200 {status: "active", coverage, lastErrorCode: null, activatedAt}
Figure 1 — An accepted request finishes in the background. A 202 on subscribe means the subscription is recorded and its delivery queue exists; the outcome reaches you later, in-band as a control message or on demand from GET /subscriptions/{id}. Delete works the same way: the queue is removed inside the request, and the worker releases the processors afterwards.
Errors and codes¶
Every failure the API answers has a non-2xx status and a JSON body with an error sentence. error is written for people and may be reworded; where a refusal has a code, that code is stable and is what programs should branch on.
| Status | Code | When |
|---|---|---|
400, 404, 422, 502 |
see below | POST /subscriptions refused the request. |
409 |
SLUG_TAKEN |
Creating or updating a tag or a role, or creating an organization, with a slug that is already in use. |
409 |
NAME_TAKEN |
Creating or updating a role, or creating an organization, with a name that is already in use. |
409 |
ALIAS_TAKEN |
Creating or updating a lens with an alias that is not available. |
400 |
CURSOR_MISMATCH |
A list request carried a cursor that cannot continue this list. See Lists. |
400 |
INVALID_REQUEST |
Creating or updating a sensor with a sensorType that is not a sensor type, or a connectionConfig that is not a JSON object or nests more than 32 levels deep. POST /subscriptions uses the same code for its own missing fields. |
400 |
INVALID_CREDENTIALS |
Creating or updating a sensor with a credentials value that is not a valid device login. See Device logins. |
400 |
CREDENTIALS_IN_CONNECTION_CONFIG |
A sensor's connectionConfig holds a login: a key that names a credential, or a URL with user:pass@ in it. Send the login as credentials instead. See What connectionConfig may hold. |
400 |
INVALID_STREAM_URL |
A sensor's connectionConfig has a stream_url or camera_url that is not a usable URL, or an update would leave a camera with a device login and a saved URL that isn't usable. See What connectionConfig may hold. |
502 |
CREDENTIAL_STORE_UNAVAILABLE |
A sensor's device login couldn't be saved. Nothing was changed; try again in a minute. |
Any other failure carries error alone — among them a missing permission (403), a body that is not valid JSON, and a malformed ids list. A missing or invalid token (401/403) is refused before the request reaches the API, so do not expect error or code in that body. Do not match on the sentence; branch on the status instead.
These are refusals of a request. A subscription that was accepted and later failed is a different thing: it answers 200 and carries its reason in lastErrorCode — see Error codes on the Subscriptions page.
Refusal codes on POST /subscriptions¶
An example refusal:
{ "error": "This region would match 240 sensors; the limit is 200. Ask for a smaller area.", "code": "TOO_MANY_SENSORS" }
| Status | Code | Meaning |
|---|---|---|
400 |
INVALID_REQUEST |
eventTypes, geohashes or lensAlias is missing or empty. |
400 |
UNKNOWN_EVENT_TYPE |
An event type is not in the vocabulary; the message names the unknown ones. |
400 |
INVALID_REGION |
A cell is not a valid geohash, or * was mixed with cells. |
404 |
LENS_NOT_ACCESSIBLE |
The alias is unknown, or names a lens private to another organization. |
422 |
REGION_TOO_FINE |
A cell is longer than 9 characters. |
422 |
TOO_MANY_CELLS |
More than 64 cells remain after nested ones collapse. |
422 |
TOO_MANY_SENSORS |
More than 200 sensors would match. |
422 |
QUOTA_EXCEEDED |
Your organization already holds 100 subscriptions. |
502 |
BROKER_UNAVAILABLE |
The broker did not accept the delivery queue. The subscription is removed again, so you can retry. In the rare case the queue could be neither created nor removed, the subscription stays in your list as error with the code QUEUE_ORPHANED — delete it. |
The Subscriptions page explains each, lists the refusals that carry no code, and gives the order in which the checks run.
Lists: page mode and batch mode¶
The paged list endpoints in this reference — GET /sensors, GET /tags, GET /tags/all and GET /organizations/users — answer two request shapes. Which one you get depends only on the query parameters you send.
Page mode is the default: send page and pageSize (or nothing). The total is counted on every call.
Batch mode is chosen as soon as the request carries any of limit, offset or cursor; page and pageSize are then ignored. It is built for reading a long list in pieces, the way the portal loads a table as you scroll.
| Parameter | Meaning |
|---|---|
limit |
Rows per batch, 1–100. Default 50; a value above 100 is treated as 100, and an unreadable one as 50. |
offset |
Rows to skip. |
cursor |
The nextCursor of the previous batch, sent back unchanged. |
ids |
On routes that accept it (such as the tag lists), a comma-separated list of up to 100 ids. It narrows the list to those rows and never widens it. |
The list and its rows look the same as in page mode; only pagination changes:
"pagination": { "limit": 50, "offset": 0, "totalCount": 312, "hasMore": true, "nextCursor": "eyJ2Ijpb..." }
totalCountis a number on the first batch only (no cursor, offset 0) andnullon every later one. Keep the first value if you want to show a total.hasMoresays whether another batch exists. Rely on it, not on a comparison withtotalCount.nextCursor, when set, continues the list: send the same request withcursor=<nextCursor>. It is only offered for sorts on values that never change (such as creation time or name).hasMore: truewithnextCursor: nullmeans continue withoffsetinstead — the previousoffsetpluslimit.offsetis echoed when you paged by offset, and isnullwhen you paged by cursor.
A cursor belongs to the exact list it came from. Keep the sort, the search, every filter and ids the same while you follow it, and do not combine it with an offset above 0; otherwise the request is refused with 400 and the code CURSOR_MISMATCH, and you start again from the first batch. A cursor that is damaged or hand-edited gets the same answer. Rows whose sort value changes while you walk an offset-paged list (a status, a last-seen time) can be skipped or repeated; restart from the top if that matters.
GET /lenses is not paged by default: it returns the whole list as { "lenses": [...], "count": n }. Send limit, offset, cursor, search or ids and it answers one batch instead, with the same pagination block beside count (which is then the size of the batch). GET /subscriptions is never paged: it returns every subscription of the credential that has not been deleted, with count.
Endpoints at a glance¶
| Method | Path | App-client scope | Portal permission | Answers | Purpose |
|---|---|---|---|---|---|
GET |
/hello |
none | none | 200 |
Liveness check. |
GET |
/metadata |
metadata/read:all |
metadata:read |
200 |
Platform metadata: valid event types and the broker endpoint/port/vhost/exchange. Used by the SDK at startup. |
GET |
/subscriptions |
subscriptions/read:self |
subscriptions:read |
200 |
Every subscription of the calling credential that is not deleted (pending, active, error), each with lastErrorCode; a portal user passes organizationId and appClientId. |
POST |
/subscriptions |
subscriptions/write:self |
subscriptions:write |
202 |
Record a subscription and create its delivery queue; provisioning finishes in the background. |
GET |
/subscriptions/{id} |
subscriptions/read:self |
subscriptions:read |
200 |
One subscription: status, coverage report, lastErrorCode, activatedAt, queueName, event types, regions, lens alias. A :self app client reads only the subscriptions it created. |
DELETE |
/subscriptions/{id} |
subscriptions/delete:self |
subscriptions:delete |
202 |
Delete the queue now (delivery stops), release processors in the background. |
Request and response bodies, and the meaning of each refusal code, are on the Subscriptions page.
Endpoint groups¶
| Group | Page |
|---|---|
| Authentication | Authentication |
| Subscriptions & metadata | Subscriptions |
| Sensors & tags | Sensors & Tags |
| Lenses | Lenses |
| App clients | App Clients |
| Organizations & roles | Organizations & Roles |
Scope of this reference
Endpoints for template/processor publishing and platform administration are out of scope here and are not part of the public API surface.