Skip to main content
POST
Subscribe to a named query

Authorizations

X-API-Key
string
header
required

Path Parameters

query_name
string
required

The name the query was created with (POST /queries).

Body

application/json

POST /queries/{queryName}/subscriptions body: where to send matches, and how to sign them.

dest
string
required

URL callbacks are POSTed to as an EPCISQueryDocument. Must be a public https address; a private, loopback or otherwise disallowed destination is refused with 400.

Maximum string length: 2048
Pattern: ^[^\x00]{0,}$
signatureToken
string | null

Shared secret. When set, each callback carries GS1-Signature: sha256=<hex>, the HMAC-SHA256 of the exact request body keyed with this token. Write-only: never returned.

Maximum string length: 255
Pattern: ^[^\x00]{0,255}$
stream
boolean
default:false

Must be true: each capture that adds events matching the query notifies once. Scheduled subscriptions are not served.

schedule
Schedule · object | null

Not served. A request that sets it is refused with 400.

reportIfEmpty
boolean | null

Not served (scheduled subscriptions only). Setting it is refused with 400.

initialRecordTime
string | null

Not served. A request that sets it is refused with 400.

Pattern: ^[^\x00]{0,}$

Response

Created

A registered subscription, as GET returns it. The signatureToken is never included.

subscriptionID
string
required

Identifier of the subscription; use it in the URL path.

dest
string
required

URL callbacks are POSTed to.

createdAt
string<date-time>
required

When the subscription was registered.

lastNotifiedAt
string<date-time> | null

When a callback last received a 2xx answer; absent until one has.