Skip to main content
POST
Create a subscription

Authorizations

​
Authorization
string
header
required

An organization API key. Keys carry a role (read_write or read_only) and may be restricted to a namespace prefix such as acme/*, or to one namespace such as acme/prod/tenant_1. A prefix matches on a / boundary: acme/prod/tenant_1* covers acme/prod/tenant_1 and everything under acme/prod/tenant_1/, never acme/prod/tenant_12.

Headers

​
Idempotency-Key
string

One key per logical request, reused only on its retries. A key belongs to one request: within your organization, the same method, path, query and body. For 24 hours after a successful response, a request with the key and the same body gets that response back verbatim, with Idempotent-Replayed: true, and runs nothing. Only a successful response is kept, so the retry of a request that failed runs again. While the first request runs or its response is kept, the key with a different request is idempotency_key_reused (422). A request sent while one with its key is still running is rate_limited with Retry-After: 1, without running: retry it to get the first one's response. In the rare case the key can't be checked, the request runs as if it had none.

Required string length: 1 - 255

Path Parameters

​
ns
string
required

A namespace name, or a template prefix ending in /*, with any / sent as %2F: acme%2Fprod%2Ftenant_123 or acme%2Fprod%2F*.

A namespace name, or a template prefix: a namespace path ending in /*, such as acme/prod/*, which every namespace under acme/prod/ inherits judgments from. Up to 256 bytes. Never exactly . or .., which a URL path can't carry.

Required string length: 1 - 256
Pattern: ^(?!\.\.?$)[A-Za-z0-9._:/-]+(/\*)?$

Body

application/json
​
name
string
required

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
​
filters
object
required

The query's filter grammar, with its missing-field rules. Never on answers.<j>.freshness, and never on an on_read judgment. It can't be changed later.

​
events
enum<string>[]
Minimum array length: 1

entered when a document starts matching; exited when it stops matching or is deleted.

Available options:
entered,
exited
​
include
object

The attributes and answers each event carries. The fields the filter reads are always included, and state never is. At most 24 fields in all, counting those the filter reads. An on_read judgment is refused. An event waits for the answers the filter reads to settle, never for the ones only included here, which are sent as they stand.

​
endpoint
string | null

The webhook endpoint that receives the events. Null, the default, sends them to the events feed only. Its namespace_prefix must cover the namespace or template.

Pattern: ^we_[0-9a-z]{26}$
​
bulk
enum<string>
default:summary

What bulk changes send: a backfill, or a resync after a threshold edit, an activation or new composite weights. summary updates membership silently and sends one subscription.synced. deliver sends every transition, with its cause. The first sync is silent either way, and announced by subscription.synced with reason created.

Available options:
summary,
deliver

Response

Created.

​
id
string
required
Pattern: ^sub_[0-9a-z]{26}$
​
name
string
required

A judgment, attribute or threshold name. Names are path segments in field references, so they never contain ..

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
​
filters
object
required

[field, op, value], ["And" | "Or", [filters]] or ["Not", filter].

​
events
enum<string>[]
required

entered when a document starts matching; exited when it stops matching or is deleted.

Available options:
entered,
exited
​
include
object
required

The attributes and answers each event carries. The fields the filter reads are always included, and state never is. At most 24 fields in all, counting those the filter reads. An on_read judgment is refused. An event waits for the answers the filter reads to settle, never for the ones only included here, which are sent as they stand.

​
endpoint
string | null
required
Pattern: ^we_[0-9a-z]{26}$
​
bulk
enum<string>
default:summary
required

What bulk changes send: a backfill, or a resync after a threshold edit, an activation or new composite weights. summary updates membership silently and sends one subscription.synced. deliver sends every transition, with its cause. The first sync is silent either way, and announced by subscription.synced with reason created.

Available options:
summary,
deliver
​
status
enum<string> | null
required

In this namespace. Null on a template's prefix path, where each namespace syncs on its first change after the subscription exists.

Available options:
syncing,
live
​
live_at
string<date-time> | null
required

When the subscription went live in this namespace.

​
lag_ms
integer<int64> | null
required

How long the oldest change the subscription has not evaluated yet has waited, in milliseconds; 0 when it is up to date. A quiet subscription records its progress about once a minute, so a change counts only once it has waited longer than that. Null while syncing and on a template's prefix path.

Required range: x >= 0
​
warnings
object[]
required
​
created_at
string<date-time>
required

RFC 3339, UTC.

​
template
string

Present when the subscription is inherited, the template prefix it comes from, such as acme/prod/*.

Required string length: 3 - 256
Pattern: ^[A-Za-z0-9._:/-]+/\*$