Skip to content

Subscriptions

You declare event types over regions through a lens. Dory creates the delivery queue at once and answers 202 Accepted; in the background it matches sensors by their area of view, starts or reuses one processor per sensor and template, and binds the queue. The outcome — a status and a coverage report — reaches you in-band as a control message on the queue and from GET /subscriptions/{id}. For the model, see Subscriptions & Events. Most consumers should use the Application SDK rather than calling these endpoints directly.

sequenceDiagram
    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->>API: validate · record the subscription as pending
    API->>Q: create the queue (empty, consumable now)
    API-->>App: 202 {subscriptionId, queueName, status: "pending"}
    App->>Q: start consuming
    API->>W: provision (requests run one at a time, in order)
    W->>W: match sensors by area of view · choose templates · start or reuse processors · bind the queue
    W->>Q: control message type=dory.subscription.ready {coverage}
    W->>API: status → active
    Q-->>App: ready (events may already be arriving)

Figure 1 — Subscribe. 202 means accepted: provisioning is asynchronous, and the outcome arrives in-band on the same queue as the events.

Endpoints

Method Path App-client scope Portal permission Purpose
GET /metadata metadata/read:all metadata:read Valid event types + queue endpoint details.
GET /subscriptions subscriptions/read:self subscriptions:read List the caller's subscriptions — every one not deleted.
POST /subscriptions subscriptions/write:self subscriptions:write Create a subscription; answers 202.
GET /subscriptions/{id} subscriptions/read:self subscriptions:read Status, coverage report, error code.
DELETE /subscriptions/{id} subscriptions/delete:self subscriptions:delete Stop delivery now and release processors shortly after; answers 202.

A :self scope limits an app client to the subscriptions it created. See Authentication.

Errors follow the API convention: a non-2xx status with { "error": "<message>" }. A refused subscribe additionally carries "code": "<CODE>", so you can branch on the reason without matching the sentence; the Application SDK raises a typed error built from that code (see its API reference). These refusal codes are separate from the error codes a subscription carries once it has been accepted and later failed.

Create a subscription

POST /subscriptions

{
  "eventTypes": ["person", "moving"],
  "geohashes": ["dhxpfr5", "dhxpfr4b"],
  "lensAlias": "demo-lens",
  "name": "parking-monitor-prod"
}
Field Required Notes
eventTypes yes One or more event type slugs from GET /metadata. Values are trimmed and duplicates dropped.
geohashes yes One or more geohash cells of 1–9 characters, or * on its own for everywhere you can see. Case-insensitive; duplicates and cells nested inside a coarser one are dropped; at most 64 cells may remain. Regions select sensors by their area of view (see below).
lensAlias yes Alias of a lens you may use: one of your organization's own lenses, or any public lens.
name no Human-readable label; defaults to Subscription <timestamp>.

The organization and the app client are taken from your token, never from the body.

What a region means

A region does not filter events; it selects sensors. A sensor is matched when its area of view intersects one of your cells — your own organization's sensors plus any organization's public sensors, active and not decommissioned. Every event those sensors' processors publish for your requested types is delivered; the platform does not filter events by the geohash stamped on the message. A foreign sensor's connection details and metadata are never exposed to you.

Templates come from the lens: those with an approved, active version that emit at least one requested event type. Per sensor type, Dory picks the smallest set of templates that covers your request and runs one processor per (sensor, template) pair. Processors are shared — if another subscription already runs the same pair, yours is attached to it rather than starting a second one.

Response

202 Accepted:

{
  "subscriptionId": "3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
  "queueName": "sub.acme.3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
  "status": "pending",
  "eventTypes": ["person", "moving"],
  "geohashes": ["dhxpfr5", "dhxpfr4b"]
}

eventTypes and geohashes are echoed as stored: trimmed and de-duplicated, with cells lower-cased and nested cells collapsed. Accepted means accepted, not provisioned:

  • The delivery queue already exists and you can start consuming it immediately.
  • Events can arrive before the ready control message — a processor reused from another subscription may already be publishing when your queue is bound.
  • Do not retry a 202. If the internal hand-off to the provisioning worker fails, the answer is still 202: the subscription is real, its queue exists, and the hourly backstop provisions it. A retry would create a second subscription for a first one that is only late.
  • The outcome arrives as a ready (or error) control message in the queue, and from GET /subscriptions/{id}.

Nothing matched is not an error

A subscription whose regions hold no eligible sensor, or whose lens has no template for the requested types, is still created and still becomes active — with a coverage report in which coverage.event_types.<type>.reason says why each type is not covered. Coverage is re-evaluated every hour, so the subscription fills in on its own when a sensor is installed or a template is added.

Refusals

A request that cannot be honoured is refused before anything is created — no subscription, no queue — with one exception: a 502, where the subscription was recorded and is then undone. The body is { "error": "...", "code": "..." }; where the table shows no code, the body carries none.

Status Code When
400 — The body is not valid JSON, or not a JSON object.
400 INVALID_REQUEST eventTypes, geohashes or lensAlias is missing or empty.
400 INVALID_REGION A cell is not a valid geohash, or * was mixed with cells.
400 UNKNOWN_EVENT_TYPE An event type is not in the vocabulary; the message names the unknown ones.
400 — No organization could be resolved from the token.
401 — No token.
403 — The token is invalid or expired, the caller lacks subscriptions:write, or its credential may not act for the organization (for example, an app client that is not active).
404 LENS_NOT_ACCESSIBLE The alias is unknown, or names a lens that is private to another organization — the same answer for both.
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 QUOTA_EXCEEDED Your organization already holds 100 subscriptions (deleted ones excluded; pending and error ones count). Delete one first.
422 TOO_MANY_SENSORS The regions would match more than 200 sensors. Ask for a smaller area.
502 BROKER_UNAVAILABLE The message broker did not accept the delivery queue. The subscription is removed again and 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.

A missing token (401) or an invalid or expired one (403) is refused before the request reaches any of these checks. The rest run in this order: the body's shape, then the organization and permission, then the lens, then the event types, then the three cost limits, and finally the queue. Authorization comes before every lookup, so a caller without subscriptions:write cannot use the later refusals to probe which lenses exist.

flowchart TB
    A["POST /subscriptions"] --> B{"Body shape"}
    B -- "missing or empty eventTypes, geohashes or lensAlias" --> E1["400 INVALID_REQUEST"]
    B -- "malformed cell, or * mixed with cells" --> E2["400 INVALID_REGION"]
    B -- "a cell longer than 9 characters" --> E3["422 REGION_TOO_FINE"]
    B -- ok --> C{"Organization and permission"}
    C -- "no organization resolved from the token" --> E4["400"]
    C -- "no subscriptions:write" --> E5["403"]
    C -- ok --> D{"Lens alias"}
    D -- "unknown, or private to another organization" --> E6["404 LENS_NOT_ACCESSIBLE"]
    D -- "yours, or public" --> F{"Event types known?"}
    F -- no --> E7["400 UNKNOWN_EVENT_TYPE"]
    F -- yes --> G{"Within the limits?"}
    G -- "more than 64 cells after nested ones collapse" --> E8["422 TOO_MANY_CELLS"]
    G -- "organization already holds 100" --> E9["422 QUOTA_EXCEEDED"]
    G -- "more than 200 sensors would match" --> E10["422 TOO_MANY_SENSORS"]
    G -- ok --> H["Record the subscription · create the queue"]
    H -- "broker refused the queue" --> E11["502 BROKER_UNAVAILABLE — the record is undone, retry"]
    H -- ok --> I["202 Accepted"]

Figure 2 — The refusals of POST /subscriptions in the order they are checked, each with its code. Nothing before the record step creates anything, and a broker refusal is undone.

Limits

  • 64 cells per subscription, after nested cells collapse.
  • 200 sensors matched per subscription.
  • 100 subscriptions per organization at once, deleted ones excluded.
  • 9 characters is the finest cell; * on its own means everywhere you can see.

Read a subscription

GET /subscriptions/{id} is the pull side of the same facts the control messages carry: status, coverage report, error code, and when it became active. Use it whenever you would rather poll — and when you connect more than an hour after ready was published, because messages in the queue expire after one hour.

200 OK:

{
  "id": "3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
  "organizationId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
  "appClientId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "name": "parking-monitor-prod",
  "description": null,
  "status": "active",
  "boundSensorCount": 3,
  "queueName": "sub.acme.3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
  "eventTypes": ["person", "moving"],
  "geohashes": ["dhxpfr5", "dhxpfr4b"],
  "lensAlias": "demo-lens",
  "coverage": {
    "event_types": {
      "person": { "covered": true },
      "moving": { "covered": false, "reason": "NO_TEMPLATE_EMITS_IT" }
    },
    "sensors_matched": 3,
    "sensors_served": 3,
    "processors_started": 2,
    "processors_reused": 1
  },
  "lastErrorCode": null,
  "createdAt": "2026-09-12T09:14:03.211Z",
  "updatedAt": "2026-09-12T09:14:09.870Z",
  "activatedAt": "2026-09-12T09:14:09.870Z",
  "deletedAt": null
}

These seventeen fields are the whole response.

Field Meaning
id, name, description The subscription and its label.
organizationId, appClientId The organization the subscription belongs to, and the app client that created it.
status pending, active, deleting or error — see Statuses.
boundSensorCount How many sensors currently serve the subscription; 0 until the worker has matched sensors for it.
queueName The delivery queue.
eventTypes, geohashes What you asked for, as stored.
lensAlias The alias of the lens the subscription runs through, or null if that lens has since been deleted.
coverage The coverage report, written when provisioning finishes and on every hourly re-check; null while pending.
lastErrorCode On a subscription in error, one of the four error codes; null on every other status.
createdAt, updatedAt, activatedAt, deletedAt activatedAt is set when provisioning finishes; deletedAt is always null on this route, because a deleted subscription answers 404.

The response never carries the platform's internal diagnostic for a failure — only the code. See Error codes.

Refusals:

Status When
400 {id} is not a UUID.
401 No token, or a credential the platform does not recognize.
403 The token is invalid or expired.
404 No such subscription, it has been deleted, or it belongs to another organization — the same answer for all three.
403 The caller is in the right organization but lacks subscriptions:read.
403 The caller is an app client with a :self scope that did not create this subscription ("You can only read subscriptions you created").

List subscriptions

GET /subscriptions

There are two kinds of caller:

  • An app client sends no parameters. The organization and the app client are taken from the token, and the list holds the subscriptions that credential created.
  • A portal user passes ?organizationId=<org>&appClientId=<client> to see the subscriptions of one app client in that organization. Omitting organizationId answers 400 ("Query parameter 'organizationId' is required"), omitting appClientId answers 400 ("Query parameter 'appClientId' is required"), and an app client that belongs to another organization answers 404 ("App client not found in this organization").

A caller without subscriptions:read in the organization answers 403.

The body is { "subscriptions": [ ... ], "count": N }, newest first. Every subscription not deleted is listed — pending, active and error alike — so you can see what is still provisioning and what needs attention. A subscription leaves the list the moment its delete is accepted. The list is not paged: it returns every such subscription in one response.

{
  "subscriptions": [
    {
      "id": "3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
      "organizationId": "9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f",
      "name": "parking-monitor-prod",
      "appClientId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "description": null,
      "status": "active",
      "boundSensorCount": 3,
      "queueName": "sub.acme.3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
      "createdAt": "2026-09-12T09:14:03.211Z",
      "updatedAt": "2026-09-12T09:14:09.870Z",
      "activatedAt": "2026-09-12T09:14:09.870Z",
      "deletedAt": null,
      "geohashes": ["dhxpfr5", "dhxpfr4b"],
      "eventTypes": ["person", "moving"],
      "lensId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "coverage": {
        "event_types": {
          "person": { "covered": true },
          "moving": { "covered": false, "reason": "NO_TEMPLATE_EMITS_IT" }
        },
        "sensors_matched": 3,
        "sensors_served": 3,
        "processors_started": 2,
        "processors_reused": 1
      },
      "lastErrorCode": null,
      "attempts": 0,
      "releasedAt": null
    }
  ],
  "count": 1
}

Each entry carries the same fields as the single read, with three differences:

  • The lens is named by its id (lensId), not resolved to lensAlias.
  • attempts counts the background worker's runs on this subscription that have not finished since its last successful one.
  • releasedAt is always null here: only a deleted subscription is released, and deleted subscriptions are not listed.

lastErrorCode behaves exactly as on the single read: one of the error codes on an error row, null otherwise.

Delete a subscription

DELETE /subscriptions/{id} → 202 Accepted:

{
  "subscriptionId": "3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
  "status": "deleting"
}

Inside the request, the subscription is marked deleting and leaves every list and count from that moment; then the delivery queue is deleted, which removes its bindings with it and cancels your consumer at once — delivery has stopped by the time you read the response. Afterwards, in the background, the worker drops the subscription's bindings from its record and stops the processors no other subscription uses; a processor shared with another subscription keeps running. The record is kept, as deleting.

A delete is allowed from any status, including pending and error — deleting is the remedy for every error code. Provisioning and release requests are processed one at a time, in the order they were made, so a release always runs after any provisioning still queued for the same subscription.

Refusals:

Status When
400 {id} is not a UUID.
401 No token, or a credential the platform does not recognize.
403 The token is invalid or expired.
404 No such subscription, already deleted, or another organization's — the same answer for all three. Treat it as a no-op: the subscription is gone.
403 The caller is in the right organization but lacks subscriptions:delete.
403 The caller is an app client with a :self scope that did not create this subscription ("You can only delete subscriptions you created"). A subscription is its creator's; the SDK keeps its record of one it was refused.
sequenceDiagram
    participant App as Your application
    participant API as Dory API
    participant Q as Delivery queue
    participant W as Provisioning worker
    App->>API: DELETE /subscriptions/{id}
    API->>API: authorize (row first) · mark deleting
    API->>Q: delete the queue — the consumer is cancelled now
    API->>W: release
    API-->>App: 202 {subscriptionId, status: "deleting"}
    W->>W: drop the bindings · stop processors no other subscription uses
    Note over App,API: a repeat DELETE answers 404 — already gone

Figure 3 — Delete. Delivery stops inside the request (the queue goes, your consumer is cancelled); processors are released afterwards; a repeat answers 404.

Statuses

Status Meaning
pending Accepted; the worker has not finished provisioning. The queue already exists.
active Provisioned. The coverage report may be empty — see Nothing matched is not an error above.
deleting Delete accepted; the queue is gone and the processors are being released. No longer listed.
error The subscription could not be set up; lastErrorCode says which of the four error codes applies. Delete it and subscribe again.

Apart from subscriptions created before the current delivery system, only a pending subscription moves to error. A failure while re-checking an active subscription is retried on the next hourly run; the subscription stays active.

stateDiagram-v2
    [*] --> pending: POST accepted (202)
    pending --> active: provisioning finished · ready message
    pending --> error: broker refused or five failed runs (error message), or queue orphaned at create (no message)
    active --> active: hourly re-check · updated message when coverage changed
    pending --> deleting: DELETE (202)
    active --> deleting: DELETE (202)
    error --> deleting: DELETE (202)
    deleting --> [*]: processors released

Figure 4 — Subscription statuses: which transitions exist, who makes them, and which control message announces each.

Error codes

A subscription in error carries one code in lastErrorCode. The API returns the code and nothing else about the failure; the portal and the Application SDK turn each code into the same plain sentence.

Code What happened What you are told
BROKER_REFUSED The message broker refused a provisioning request outright, so retrying cannot fix it. "The platform couldn't set up this subscription. Delete it and try again; if it keeps failing, contact support with the subscription ID."
PROVISIONING_FAILED Provisioning kept failing on temporary problems and ran out of attempts (five runs). "The platform couldn't set up this subscription. Delete it and try again; if it keeps failing, contact support with the subscription ID."
QUEUE_ORPHANED Creating the delivery queue failed, and removing it again failed too. Your subscribe request answered 502 BROKER_UNAVAILABLE. "This subscription could not be set up. Delete it and subscribe again."
LEGACY_RESUBSCRIBE The subscription was created before the current delivery system. "This subscription was created before the current delivery system. Delete it and subscribe again."

The remedy is the same for all four: delete the subscription and subscribe again. Only BROKER_REFUSED and PROVISIONING_FAILED are also announced by an error control message on the queue; the other two you find through GET /subscriptions/{id} or the list.

The coverage report

The coverage report is the platform's answer to "what did you match for me?". It arrives in the ready control message, in every updated message, and in GET /subscriptions/{id}:

{
  "event_types": {
    "person": { "covered": true },
    "moving": { "covered": false, "reason": "NO_TEMPLATE_EMITS_IT" }
  },
  "sensors_matched": 3,
  "sensors_served": 3,
  "processors_started": 2,
  "processors_reused": 1
}
Field What it says
event_types For each event type you requested: covered (true or false) and, when not covered, a reason.
sensors_matched How many eligible sensors have an area of view intersecting your regions.
sensors_served How many of those have at least one processor producing your event types.
processors_started How many processors the latest provisioning or re-check run started for you.
processors_reused How many existing live processors that run attached you to.
Reason In plain words
LENS_NOT_ACCESSIBLE The lens no longer exists, or is now private to another organization. The subscription stays active and recovers when the lens is available again.
NO_SENSORS_IN_REGION No eligible sensor's area of view intersects your regions.
NO_TEMPLATE_EMITS_IT No template in the lens with an approved, active version produces this event type.
NO_COMPATIBLE_SENSOR A template does produce it, but no matched sensor is of a type that template supports.

The report carries counts, never identities: no sensor ids, sensor names, coordinates or processor ids. An empty report is not an error.

How it changes

Every hour the platform re-matches each active subscription from what you asked for and compares the result with what is serving you now. The re-check catches a sensor being installed, published, unpublished, moved or decommissioned; the lens being made private or deleted (every type becomes LENS_NOT_ACCESSIBLE, the subscription stays active, and it recovers when the lens is opened again); a template being attached to or detached from the lens, or its version revoked; and a processor that failed or was terminated, which is re-added on a live one. You receive an updated control message only when the per-type coverage or the sensor counts changed; the two processor counts describe a single run and never trigger one on their own.

Control messages on the delivery queue

Besides events, the worker drops three kinds of control message into your delivery queue:

AMQP type When Payload
dory.subscription.ready When provisioning finished. subscription_id, status: "active" and the coverage report.
dory.subscription.updated Each time the hourly re-check changes your coverage. subscription_id, status: "active" and the new coverage report.
dory.subscription.error Provisioning gave up. subscription_id, status: "error", a code (BROKER_REFUSED or PROVISIONING_FAILED) and a message — the sentence for that code from Error codes.

You tell them apart from events by the AMQP type property, which events never set. They are delivered through the queue's own name rather than through a binding, and use the same JSON envelope as an event:

{
  "schema_version": "0.1",
  "message_id": "b7e2d9c4-1f3a-4c5e-8d6b-2a9f0e1c3d4b",
  "timestamp": "2026-09-12T09:14:09.870Z",
  "payload": {
    "subscription_id": "3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "status": "active",
    "coverage": {
      "event_types": {
        "person": { "covered": true },
        "moving": { "covered": false, "reason": "NO_TEMPLATE_EMITS_IT" }
      },
      "sensors_matched": 3,
      "sensors_served": 3,
      "processors_started": 2,
      "processors_reused": 1
    }
  }
}

An error message carries code and message in place of coverage:

{
  "schema_version": "0.1",
  "message_id": "d4c3b2a1-9f8e-4d7c-b6a5-0f1e2d3c4b5a",
  "timestamp": "2026-09-12T10:02:41.118Z",
  "payload": {
    "subscription_id": "3f7a1c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "status": "error",
    "code": "PROVISIONING_FAILED",
    "message": "The platform couldn't set up this subscription. Delete it and try again; if it keeps failing, contact support with the subscription ID."
  }
}

What to expect as a consumer

  • The Application SDK handles control messages itself and never passes them to your event callback.
  • An SDK older than 1.2.0 keeps receiving events, but sees each control message as one callback call whose object has subscription_id and status and no event payload.
  • The queue is named sub.<organization-slug>.<subscription-id> (returned as queueName), is durable, expires a message after one hour, and holds at most 10 000 messages. A consumer that connects more than an hour after ready reads its status from GET /subscriptions/{id} instead.
  • Events are delivered at-least-once; de-duplicate on message_id.

Authorization

Portal users are gated by the subscriptions:read, subscriptions:write and subscriptions:delete permissions in the subscription's organization; app clients by the subscriptions/read:self, subscriptions/write:self and subscriptions/delete:self scopes. On POST /subscriptions the permission is checked before any lookup. On the {id} routes the subscription is loaded first: missing, deleted or another organization's answers 404 — identical, so nothing reveals that an id exists elsewhere; a member of the right organization without the permission answers 403; and an app client with a :self scope that did not create the subscription answers 403 ("You can only read/delete subscriptions you created"), which is what the SDK relies on to keep, not forget, the subscription.

flowchart TB
    A["GET or DELETE /subscriptions/{id}"] --> B{"Subscription exists and is not deleted?"}
    B -- no --> N1["404 Subscription not found"]
    B -- yes --> C{"Caller belongs to the subscription's organization?"}
    C -- no --> N2["404 — the same answer as not found"]
    C -- yes --> D{"Holds subscriptions:read / subscriptions:delete?"}
    D -- no --> N3["403 Missing permission"]
    D -- yes --> E{"App client with a :self scope that did not create it?"}
    E -- yes --> N4["403 You can only read/delete subscriptions you created"]
    E -- "no — its creator, or a portal user" --> OK["Proceed"]

Figure 5 — Authorization on GET and DELETE /subscriptions/{id}. The row is loaded first, which is why "missing" and "another organization's" get the same 404, and, once the token has been accepted, only a member of the right organization can see a 403.