Subscribers
Subscribers are the end users who hear about a post's updates. A post's author, voters and commenters follow it automatically, and anyone else can follow it by choice. An unfollow sticks: voting later doesn't make them follow the post again.
The examples read your API key and your workspace's base URL from two shell variables. Set them once, with your workspace's id in place of ws_... (API keys says where to find both):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." List a post's subscribers#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ subscribersAny API key: Read or Read and write
Returns the end users who follow the post, the earliest first.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Query parameters
limitintegerHow many items to return in the page.
From 1 to 100Defaults to
25cursorstringThe previous page's
next_cursor, to get the next page.At most 1,024 characters
Responses
- 200OKA page of subscribers. The subscriber objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/subscribers" {
"data": [
{
"end_user": {
"id": "user_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"companies": [
{
"id": "company_01h455vb4pex5vsknk084sn02q",
"external_id": "acme",
"name": "Acme",
"value": 120000
}
],
"email": "dana@example.com",
"external_id": "u-8412",
"kind": "user",
"name": "Dana Kim",
"traits": {
"plan": "enterprise",
"seats": 40
},
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"banned_at": null,
"email_verified_at": null,
"erased_at": null
},
"reason": "author",
"created_at": "2026-09-28T14:03:12.482Z"
}
],
"next_cursor": null,
"has_more": false
}Add a subscriber#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ subscribersAn API key with Read and write access
Makes an end user follow the post. With an API key, end_user is required: it names the customer who follows, who is created if new. This undoes an earlier unfollow.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Headers
Idempotency-KeystringMakes a retry safe: for 24 hours, the same request with the same key returns the first response instead of repeating the change. Use 1 to 255 visible ASCII characters, without spaces, such as a UUID. See Idempotency.
1 to 255 characters
Request body
application/jsonrequiredend_userobjectrequiredWho follows the post: an existing end user by
id, or a customer byexternal_idoremail, who's created if new.Child fields (5)
idstringAn existing end user's id. Send it alone, without the other fields.
Starts with
user_external_idstringThe customer's id in your system. Swingback looks for the customer by it first.
1 to 255 characters
emailstring · emailThe customer's email. Without a match on
external_id, Swingback looks for the customer by email.At most 254 characters
namestringThe customer's name, which replaces the one Swingback has.
1 to 100 characters
avatar_urlstring · URLThe address of the customer's avatar,
httporhttps, which replaces the one Swingback has.At most 2,048 characters
Responses
- 200OKThe end user already followed the post. Returns a subscriber object.
- 201CreatedThe end user now follows the post. Returns a subscriber object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"end_user": {
"external_id": "u-9031",
"email": "lee@example.com",
"name": "Lee Park"
}
}' \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/subscribers" {
"end_user": {
"id": "user_01h455vb4pex5vsknk084sn04s",
"avatar_url": null,
"companies": [],
"email": "lee@example.com",
"external_id": "u-9031",
"kind": "user",
"name": "Lee Park",
"traits": {},
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"banned_at": null,
"email_verified_at": null,
"erased_at": null
},
"reason": "manual",
"created_at": "2026-09-28T14:03:12.482Z"
}Remove a subscriber#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ subscribers/ {end_user_id}An API key with Read and write access
Makes the end user unfollow the post. The unfollow sticks: voting or commenting later doesn't make them follow the post again.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_end_user_idstringrequiredThe end user's id.
Starts with
user_
Responses
- 204No ContentThe end user no longer follows the post.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/subscribers/user_01h455vb4pex5vsknk084sn04s" The response is 204 No Content, with no body.
The subscriber object#
Fields
end_userobjectAn end user object.
reasonstringWhy the end user follows the post.
manualmeans they chose to follow it.One ofauthorvotercommentermanualcreated_atstring · date-time
Example
{
"end_user": {
"id": "user_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"companies": [
{
"id": "company_01h455vb4pex5vsknk084sn02q",
"external_id": "acme",
"name": "Acme",
"value": 120000
}
],
"email": "dana@example.com",
"external_id": "u-8412",
"kind": "user",
"name": "Dana Kim",
"traits": {
"plan": "enterprise",
"seats": 40
},
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"banned_at": null,
"email_verified_at": null,
"erased_at": null
},
"reason": "author",
"created_at": "2026-09-28T14:03:12.482Z"
}