Skip to content

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

https://api.streetscapes.ai/v1

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:

Authorization: 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 — organizationId as 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 :self restrict a client to the resources it created; :all covers the whole organization. On routes addressed by an id, a :self credential that reaches a subscription created by another credential in the same organization gets 403; a subscription in another organization gets 404.
  • Lists. Paged list endpoints answer in two shapes: page mode (page, pageSize) and batch mode (limit, offset, cursor), each with its own pagination block. 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 is pending until that completes, then active (its coverage report may be empty — matching nothing is not an error); a deleted one reports deleting; one that could not be set up reports error, with its reason code in lastErrorCode — delete it and subscribe again. Learn the outcome either from the control message the worker drops into the delivery queue (ready, later updated whenever coverage changes, or error when the worker gives up — the SDK handles these and never passes them to your event handler) or by reading GET /subscriptions/{id}, which returns status, the coverage report, lastErrorCode and activatedAt. Not every error is announced on the queue, so the read is the one to trust. A 202 means 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. 404 means 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 gets 403.

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.

{ "error": "Tag with this slug already exists in the organization", "code": "SLUG_TAKEN" }
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.

"pagination": { "page": 2, "pageSize": 25, "totalCount": 312, "totalPages": 13 }

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..." }
  • totalCount is a number on the first batch only (no cursor, offset 0) and null on every later one. Keep the first value if you want to show a total.
  • hasMore says whether another batch exists. Rely on it, not on a comparison with totalCount.
  • nextCursor, when set, continues the list: send the same request with cursor=<nextCursor>. It is only offered for sorts on values that never change (such as creation time or name). hasMore: true with nextCursor: null means continue with offset instead — the previous offset plus limit.
  • offset is echoed when you paged by offset, and is null when 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.