Subscriptions API
Subscription endpoints manage workspace subscriptions, their state, testing, and delivery logs.
GET /api/v1/subscriptions
Returns subscriptions for the current workspace/account.
Arguments: none. The list is filtered by the backend using the current selected workspace.
Payload: none.
Response: SubscriptionView[].
POST /api/v1/subscriptions
Creates a subscription directly by rules or by template.
Arguments: none.
Payload for direct trigger subscription:
| Field | Required | Description |
|---|---|---|
template | No | Usually null or omitted in direct mode. |
rules | Yes | Array of rules. At least one rule is required. |
rules[].trigger | Yes | Trigger fullname. |
rules[].conditions | Yes | Conditions object for rule filtering. |
resources | Yes | Array of resource fullnames. |
actions | No | Delivery actions. |
meta.title | No | Subscription title. |
state | No | on or off. |
Payload for template subscription:
| Field | Required | Description |
|---|---|---|
template.id | Yes | Template id. |
template.inputs | Yes | Values for template input schema. |
template.topics | Yes | Selected topic names. |
resources | Yes | Array of resource fullnames. |
actions | No | Delivery actions. |
meta.title | No | Subscription title. |
state | No | on or off. |
Response: SubscriptionView.
GET /api/v1/subscriptions/:id
Returns a subscription.
Arguments:
| Argument | Location | Description |
|---|---|---|
id | Path | Subscription id. |
Payload: none.
Response: SubscriptionView.
POST /api/v1/subscriptions/:id
Updates a subscription.
Arguments:
| Argument | Location | Description |
|---|---|---|
id | Path | Subscription id. |
Payload: same shape as POST /api/v1/subscriptions.
Response: SubscriptionView.
DELETE /api/v1/subscriptions/:id
Deletes a subscription.
Arguments:
| Argument | Location | Description |
|---|---|---|
id | Path | Subscription id. |
Payload: none.
Response: OperationResult.
POST /api/v1/subscriptions/:id/state
Changes subscription state.
Arguments:
| Argument | Location | Description |
|---|---|---|
id | Path | Subscription id. |
Payload:
| Field | Required | Description |
|---|---|---|
state | Yes | on, off, or blocked. |
issue | No | Human-readable block/disable reason. |
Response: SubscriptionView.
POST /api/v2/subscriptions/test
Tests an existing subscription or a draft subscription.
Arguments: none.
Payload:
| Field | Required | Description |
|---|---|---|
subscription | One of | Existing subscription id. |
draft | One of | Draft payload with the same shape as subscription.save.params. |
ruleIndex | No | Rule index to test. |
mode | No | preview or send. |
input | No | Raw source item/test input. |
test.source | No | Source item object. |
test.itemIndex | No | Source item index. |
test.match.hash | No | Existing match hash. |
test.match.index | No | Existing match index. |
Response: SubscriptionTestResult.
GET /api/v2/subscriptions/alerts/history
Returns subscription logs for the current workspace.
Arguments:
| Argument | Location | Description |
|---|---|---|
limit | Query | 50, 100, 250, or 500. |
status | Query | delivered, failed, rate_limited, blocked. |
direction | Query | before or after. |
datetime | Query | Cursor date-time. |
Payload: none.
Response: SubscriptionAlertLog[].
GET /api/v2/subscriptions/:id/alerts/history
Returns logs for a specific subscription.
Arguments:
| Argument | Location | Description |
|---|---|---|
id | Path | Subscription id. |
limit | Query | 50, 100, 250, or 500. |
status | Query | Optional status filter. |
direction | Query | before or after. |
datetime | Query | Cursor date-time. |
Payload: none.
Response: SubscriptionAlertLog[].