Subscriptions
Subscribe or unsubscribe from tables and records to control which notifications you receive. Subscribing to a table sends you notifications for all activity on that table. Subscribing to a record sends you notifications for that specific record.
All endpoints require the caller to be a member of the table's workspace. Read-only members can subscribe.
Subscribe to a table
POST /api/subscriptions/<table_id>/subscribe
| Field | Type | Notes |
|---|---|---|
force |
bool | If true, no-op when already subscribed instead of returning an error |
Returns {"ok": true, "subscribed": true}.
Unsubscribe from a table
POST /api/subscriptions/<table_id>/unsubscribe
| Field | Type | Notes |
|---|---|---|
force |
bool | If true, no-op when not subscribed instead of returning an error |
Returns {"ok": true, "subscribed": false}.
Subscribe to a record
POST /api/subscriptions/<table_id>/<record_id>/subscribe
| Field | Type | Notes |
|---|---|---|
force |
bool | If true, no-op when already subscribed instead of returning an error |
Returns {"ok": true, "subscribed": true}.
Unsubscribe from a record
POST /api/subscriptions/<table_id>/<record_id>/unsubscribe
| Field | Type | Notes |
|---|---|---|
force |
bool | If true, no-op when not subscribed instead of returning an error |
Returns {"ok": true, "subscribed": false}.
Subscribe to many records at once
POST /api/subscriptions/<table_id>/subscribeBatch
| Field | Type | Notes |
|---|---|---|
record_ids |
int[] | The records to follow. Duplicates and already-followed records are ignored. |
Returns {"ok": true, "count": 3, "subscribed": true}, where count is the number of
records actually subscribed. Ids that do not exist in the table are skipped, so count
may be lower than the number you sent — compare the two to detect stale ids. If none of
the ids exist the call fails with No records specified.
Unsubscribe from many records at once
POST /api/subscriptions/<table_id>/unsubscribeBatch
| Field | Type | Notes |
|---|---|---|
record_ids |
int[] | The records to unfollow. Ids you are not following are ignored. |
Returns {"ok": true, "count": 3, "subscribed": false}.
Both batch endpoints are idempotent — re-sending the same ids is safe. Read-only API keys are rejected. An empty record_ids returns an error.
Check subscription status
POST /api/subscriptions/<table_id>/status
| Field | Type | Notes |
|---|---|---|
record_id |
int | Optional — also check record-level subscription |
Returns:
{
"table": true,
"record": false
}
Force flag
By default, subscribing when already subscribed (or unsubscribing when not subscribed) returns an error. Pass "force": true to make the call idempotent — it succeeds silently when already in the target state. This is useful for integrations that want to ensure a subscription exists without tracking current state.
Read-only API keys can read subscription status but cannot change subscriptions.
Admin: manage table followers
Workspace admins can view and curate the table-level follower list for other members. These endpoints require the caller to be an admin of the table's workspace; non-admins receive an error.
List followers
POST /api/subscriptions/<table_id>/followers
Returns one entry per workspace member (pending invites excluded), with their current table-level follow state:
[
{"user_id": 12, "displayName": "Alice", "emailAddress": "alice@example.com", "following": true, "is_self": true},
{"user_id": 34, "displayName": "Bob", "emailAddress": "bob@example.com", "following": false, "is_self": false}
]
Set a follower
POST /api/subscriptions/<table_id>/setFollower
| Field | Type | Notes |
|---|---|---|
user_id |
int | Must be a current member of the workspace |
following |
bool | true adds a table-level follow, false removes it |
Returns {"user_id": 34, "following": true}. Idempotent - repeating the same call is a no-op. Removing also clears a follow the member added themselves. Read-only API keys are rejected. The member is not notified that they were added; they simply begin (or stop) receiving the table's notifications.