Skip to content
Swingback, home

API reference

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):

Terminal
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..."
Download the OpenAPI specJSON

List a post's subscribers#

GET/v1/workspaces/{workspace_id}/posts/{post_id}/subscribers

Any API key: Read or Read and write

Returns the end users who follow the post, the earliest first.

Path parameters

  • workspace_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Query parameters

  • limitinteger

    How many items to return in the page.

    From 1 to 100Defaults to 25

  • cursorstring

    The previous page's next_cursor, to get the next page.

    At most 1,024 characters

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/subscribers"
Response · 200 OK
{
  "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#

POST/v1/workspaces/{workspace_id}/posts/{post_id}/subscribers

An 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_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

Headers

  • Idempotency-Keystring

    Makes 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/jsonrequired
  • end_userobjectrequired

    Who follows the post: an existing end user by id, or a customer by external_id or email, who's created if new.

    Child fields (5)
    • idstring

      An existing end user's id. Send it alone, without the other fields.

      Starts with user_

    • external_idstring

      The customer's id in your system. Swingback looks for the customer by it first.

      1 to 255 characters

    • emailstring · email

      The customer's email. Without a match on external_id, Swingback looks for the customer by email.

      At most 254 characters

    • namestring

      The customer's name, which replaces the one Swingback has.

      1 to 100 characters

    • avatar_urlstring · URL

      The address of the customer's avatar, http or https, which replaces the one Swingback has.

      At most 2,048 characters

Responses

  • 200
    OKThe end user already followed the post. Returns a subscriber object.
  • 201
    CreatedThe end user now follows the post. Returns a subscriber object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
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"
Response · 201 Created
{
  "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#

DELETE/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_idstringrequired

    Your workspace's id, shown under Settings → Sign-in.

    Starts with ws_

  • post_idstringrequired

    The post's id.

    Starts with post_

  • end_user_idstringrequired

    The end user's id.

    Starts with user_

Responses

  • 204
    No ContentThe end user no longer follows the post.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
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_userobject

    An end user object.

  • reasonstring

    Why the end user follows the post. manual means they chose to follow it.

    One ofauthorvotercommentermanual
  • created_atstring · date-time

Example

The subscriber object
{
  "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"
}

Search pages, sections and code: a setting, an event, a method.