Skip to content
Swingback, home

API reference

Posts

Posts are the feedback itself: a title and a Markdown body on a board, with a status, tags and votes. Filter and sort them, create them on behalf of your customers, and move them through their statuses.

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 posts#

GET/v1/workspaces/{workspace_id}/posts

Any API key: Read or Read and write

Returns live posts, or the posts in the trash with deleted=true. Merged posts are left out, and so are the posts on a board in the trash, unless they're in the trash themselves: restore the board to list them. Every sort ends on the id, so posts with equal values keep one order. A post whose value changes while you page, such as a new vote under top, can repeat or be skipped. q searches titles and bodies in the workspace's language, forgives accents and typos in titles, and sorts by relevance. A search returns at most 1,000 results.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

Query parameters

  • sortstring

    Defaults to newest, or to relevance with q. A search can only sort by relevance, and relevance needs q.

    One ofnewestoldesttoptrendingrelevancecustomer_value
  • qstring

    The words to search for.

    1 to 200 characters

  • board_idstring

    Only the posts on this board.

    Starts with board_

  • statusarray of strings

    Only the posts with any of these statuses. Repeat the parameter for each value.

    Each one ofpendingreviewplannedin_progresscompletedclosed

    At most 6 items

  • tag_idarray of strings

    Only the posts with any of these tags. Repeat the parameter for each value.

    At most 20 itemsEach starts with tag_

  • author_idstring

    Only the posts by this end user.

    Starts with user_

  • company_idstring

    Only the posts that members of this company vote for.

    Starts with company_

  • visibilitystring

    Only the public posts, or only the private ones.

    One ofpublicprivate
  • moderation_statearray of strings

    Only the posts in any of these moderation states. Repeat the parameter for each value.

    Each one ofapprovedheldrejected

    At most 3 items

  • deletedboolean

    Return the items in the trash instead of the live ones.

    Defaults to false

  • 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

  • languagestring

    The reader's language. When the workspace translates what people write (ai_translation), each post or public comment written in another language then has its text in this language in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts?status=planned&sort=top&limit=10"
Response · 200 OK
{
  "data": [
    {
      "id": "post_01h455vb4pex5vsknk084sn02q",
      "attachments": [],
      "author": {
        "id": "user_01h455vb4pex5vsknk084sn02q",
        "avatar_url": null,
        "email": "dana@example.com",
        "external_id": "u-8412",
        "kind": "user",
        "name": "Dana Kim"
      },
      "board_id": "board_01h455vb4pex5vsknk084sn02q",
      "body_html": "<p>Finance exports every report by hand.</p>",
      "body_md": "Finance exports every report by hand.",
      "comment_count": 3,
      "customer_value": 1250000,
      "language": "en",
      "merged_into_id": null,
      "moderation_flags": [],
      "moderation_state": "approved",
      "number": 42,
      "slug": "export-reports-to-csv",
      "source": "api",
      "status": "planned",
      "tags": [
        {
          "id": "tag_01h455vb4pex5vsknk084sn02q",
          "scope": "post",
          "name": "Reporting",
          "color": "#3b82f6",
          "source": "manual",
          "created_at": "2026-09-28T14:03:12.482Z",
          "updated_at": "2026-09-28T14:03:12.482Z"
        }
      ],
      "title": "Export reports to CSV",
      "translation": null,
      "visibility": "public",
      "vote_count": 17,
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z",
      "deleted_at": null,
      "edited_at": null,
      "status_changed_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Create a post#

POST/v1/workspaces/{workspace_id}/posts

An API key with Read and write access

With an API key, author is required: it names the customer the post is from, who is created if new. The author follows the post.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

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

A new post. status defaults to pending, and visibility to public.

  • authorobjectrequired

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

    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

  • board_idstringrequired

    The board to post on. It can't be in the trash.

    Starts with board_

  • titlestringrequired

    The post's title.

    1 to 200 characters

  • body_mdstring

    The post's text, in Markdown.

    At most 20,000 characters

  • asset_idsarray of strings

    Uploaded images to attach, in order, from your own uploads that aren't attached to anything yet.

    At most 4 itemsEach starts with asset_

  • statusstring

    The post's status. Defaults to pending.

    One ofpendingreviewplannedin_progresscompletedclosed
  • tag_idsarray of strings

    Tags with the post scope.

    At most 10 itemsEach starts with tag_

  • visibilitystring

    public for everyone, the default. private hides the post from other customers: only your team and the post's author see it, and the author still gets notifications about it. A post on a private board is hidden from customers whatever its visibility.

    One ofpublicprivate

Responses

  • 201
    CreatedThe new post object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X POST "$SWINGBACK_API/posts" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "board_id": "board_01h455vb4pex5vsknk084sn02q",
    "title": "Export reports to CSV",
    "body_md": "Finance exports every report by hand.",
    "author": {
      "external_id": "u-8412",
      "email": "dana@example.com",
      "name": "Dana Kim"
    }
  }'
Response · 201 Created
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 0,
  "customer_value": 0,
  "language": null,
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "pending",
  "tags": [],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 0,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

Retrieve a post#

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

Any API key: Read or Read and write

Returns a post, live or in the trash.

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

  • languagestring

    The reader's language. When the workspace translates what people write (ai_translation), each post or public comment written in another language then has its text in this language in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl

Responses

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "planned",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

Update a post#

PATCH/v1/workspaces/{workspace_id}/posts/{post_id}

An API key with Read and write access

Fields you don't send stay unchanged. A new title gives the post a new slug, and the old slug still leads to the post. A post in the trash, or on a board in the trash, returns 409 in_trash.

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_

Request body

application/jsonrequired
  • titlestring

    The post's new title. The slug follows it, and former slugs still lead to the post.

    1 to 200 characters

  • body_mdstring

    The post's new text, in Markdown.

    At most 20,000 characters

  • asset_idsarray of strings

    The images to attach, in order, in place of the current ones. Images already attached can stay; any others must be your own uploads that aren't attached to anything yet.

    At most 4 itemsEach starts with asset_

  • board_idstring

    The board to move the post to. It can't be in the trash.

    Starts with board_

  • visibilitystring

    public for everyone. private hides the post from other customers: only your team and the post's author see it, and the author still gets notifications about it. A post on a private board is hidden from customers whatever its visibility.

    One ofpublicprivate

Responses

  • 200
    OKThe updated post object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X PATCH \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Export reports to CSV and Excel"
  }' \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": null,
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv-and-excel",
  "source": "api",
  "status": "planned",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV and Excel",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": "2026-10-02T09:30:00.000Z",
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

Delete a post#

DELETE/v1/workspaces/{workspace_id}/posts/{post_id}

An API key with Read and write access

Moves the post to the trash. It stays there for 30 days, then is deleted for good. Deleting a post that's already in the trash changes nothing.

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_

Responses

  • 204
    No ContentThe post is in the trash.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q"

The response is 204 No Content, with no body.

Restore a post#

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

An API key with Read and write access

Takes the post out of the trash. If a live post took its slug in the meantime, the restored post gets a new one. Restoring a live post changes nothing.

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

Responses

  • 200
    OKThe restored post object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/restore"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "planned",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

Merge a post#

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

An API key with Read and write access

Merges the post into another post, the target. The votes and comments of the post, and of the posts already merged into it, then count and show on the target. An end user who voted for both posts counts once, from their earliest vote. Followers stay on their own post.

The merged post is read-only (409 merged) until it's unmerged, and the portal shows the target in its place. Neither post can be merged already (409 merged, 422 merge_target_merged), or be in the trash or on a board in the trash (409 in_trash). A target that doesn't exist, and a post merged into itself, return 400 validation_failed, with not_found or same_post on into_post_id.

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
  • into_post_idstringrequired

    The post to merge this one into.

    Starts with post_

Responses

  • 200
    OKThe target post 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 '{
    "into_post_id": "post_01h455vb4pex5vsknk084sn03r"
  }' \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/merge"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn03r",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn04s",
    "avatar_url": null,
    "email": "lee@example.com",
    "external_id": "u-9031",
    "kind": "user",
    "name": "Lee Park"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>We need CSV files of our reports.</p>",
  "body_md": "We need CSV files of our reports.",
  "comment_count": 4,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 17,
  "slug": "csv-export-for-reports",
  "source": "api",
  "status": "review",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "CSV export for reports",
  "translation": null,
  "visibility": "public",
  "vote_count": 24,
  "created_at": "2026-08-14T10:21:40.115Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-08-14T10:21:40.115Z"
}

Unmerge a post#

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

An API key with Read and write access

Takes a merged post out of the post it was merged into. Its votes and comments, and those of the posts merged into it, count on it again, exactly as before the merge. If the post its votes count on now, the last one in its chain of merges, is in the trash or on a board in the trash, restore that one first (409 in_trash). Unmerging a post that isn't merged changes nothing.

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

Responses

  • 200
    OKThe unmerged post object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/unmerge"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "planned",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

Change a post's status#

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

An API key with Read and write access

Records the change, and the optional note, in the post's history. Setting the status the post already has changes nothing, unless you send a note: then it returns 422 status_unchanged.

A few seconds later, the post's linked GitHub or Linear issues follow the new status, unless you send sync_issues: false or their connection doesn't send statuses to issues. With one issue, the issue follows the post forward or back; with several, they only move forward. If the workspace's routing rules create issues automatically, a post that reaches their status also gets the issues they name.

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
  • statusstringrequired

    The post's new status.

    One ofpendingreviewplannedin_progresscompletedclosed
  • note_mdstring

    Your team's note about the change, in Markdown.

    At most 5,000 characters

  • sync_issuesboolean

    Whether the post's linked issues follow the change. False leaves them as they are.

    Defaults to true

Responses

  • 200
    OKThe updated post 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 '{
    "status": "completed",
    "note_md": "Shipped in version 2.4."
  }' \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/status"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "completed",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-10-02T09:30:00.000Z"
}

List a post's status changes#

GET/v1/workspaces/{workspace_id}/posts/{post_id}/status-changes

Any API key: Read or Read and write

Returns the post's status history, newest 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/status-changes"
Response · 200 OK
{
  "data": [
    {
      "id": "change_01h455vb4pex5vsknk084sn02q",
      "actor": {
        "type": "account",
        "id": "acct_01h455vb4pex5vsknk084sn02q"
      },
      "from_status": "review",
      "note_html": "<p>Planned for the March release.</p>",
      "note_md": "Planned for the March release.",
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "to_status": "planned",
      "created_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Replace a post's tags#

PUT/v1/workspaces/{workspace_id}/posts/{post_id}/tags

An API key with Read and write access

Sets the post's tags to exactly the ones you send. An empty list removes them all.

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_

Request body

application/jsonrequired
  • tag_idsarray of stringsrequired

    The post's new tags, all with the post scope. An empty list removes every tag.

    At most 10 itemsEach starts with tag_

Responses

  • 200
    OKThe updated post object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X PUT \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_ids": [
      "tag_01h455vb4pex5vsknk084sn06v",
      "tag_01h455vb4pex5vsknk084sn02q"
    ]
  }' \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/tags"
Response · 200 OK
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "planned",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn06v",
      "scope": "post",
      "name": "Finance",
      "color": "#f59e0b",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    },
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

List a post's issue links#

GET/v1/workspaces/{workspace_id}/posts/{post_id}/issue-links

Any API key: Read or Read and write

Returns the post's links to GitHub or Linear issues, oldest first, including the links of the posts merged into it. Each link has its destination and, once the issue exists, the issue as its tracker describes it. An issue's status is the post status its state maps to, under its connection's settings. Only members create links, in the dashboard: API keys can read them.

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_

Responses

  • 200
    OKThe post's issue links. The issue link objects are all in data.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/issue-links"
Response · 200 OK
{
  "data": [
    {
      "id": "link_01h455vb4pex5vsknk084sn02q",
      "body_md": "Finance exports every report by hand.",
      "copies_comments": true,
      "copies_notes": false,
      "destination": {
        "id": "destination_01h455vb4pex5vsknk084sn02q",
        "archived": false,
        "description": "The web app's issues.",
        "enabled": true,
        "gone": false,
        "integration_id": "integration_01h455vb4pex5vsknk084sn02q",
        "kind": "github_repository",
        "name": "acme/web",
        "public": false,
        "url": "https://github.com/acme/web",
        "created_at": "2026-09-28T14:03:12.482Z",
        "updated_at": "2026-09-28T14:03:12.482Z"
      },
      "error_code": null,
      "issue": {
        "id": "issue_01h455vb4pex5vsknk084sn02q",
        "key": "#123",
        "labels": [],
        "left": null,
        "state": "open",
        "state_name": null,
        "state_reason": null,
        "status": "planned",
        "title": "Export reports to CSV",
        "url": "https://github.com/acme/web/issues/123",
        "updated_at": "2026-09-28T14:03:12.482Z"
      },
      "labels": [],
      "origin": "created",
      "post_id": "post_01h455vb4pex5vsknk084sn02q",
      "public_confirmed": false,
      "state": "linked",
      "title": "Export reports to CSV",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ]
}

The post object#

Fields

  • idstring

    Starts with post_

  • attachmentsarray of objects

    Each item is an asset object.

  • authorobject
    Child fields (6)
    • idstring

      Starts with user_

    • avatar_urlstringnullable
    • emailstring · emailnullable
    • external_idstringnullable
    • kindstring

      user for a customer, team for the team's own rows (a team member acting as themselves, an issue tracker's connection, or an imported team author), and guest for someone who wrote in the portal without signing in.

      One ofuserteamguest
    • namestringnullable
  • board_idstring

    Starts with board_

  • body_htmlstring

    body_md, rendered as sanitized HTML.

  • body_mdstring

    At most 20,000 characters

  • comment_countinteger

    How many live, public, approved comments the post has.

  • customer_valueinteger

    The sum of the values of the distinct companies whose members vote for the post.

    At least 0

  • languagestringnullable

    The language the post is written in, as the AI detected it: an ISO 639-1 code, such as ja. Null until the workspace's translation has read the post, and when the AI can't name the language.

  • merged_into_idstringnullable

    The post this one was merged into.

    Starts with post_

  • moderation_flagsarray of objects

    Why the post is held. Empty once your team has decided.

    Fields of each item (3)
    • detailstring

      What the reason found: the kinds of data for sensitive_data, separated by commas; the category for ai; why for ai_unavailable. Empty for the other reasons.

      At most 200 characters

    • reasonstring

      approval: the workspace reviews this kind of content first. sensitive_data: a card number, an IBAN, a key or a token (detail lists the kinds). links: more than 3 links. duplicate: the author wrote the same text in the last 24 hours. ai: the AI moderation found what detail names (spam, abuse, sexual, violence or personal_data). ai_unavailable: a guest's text that the AI moderation couldn't judge (detail says why).

      One ofapprovalsensitive_datalinksduplicateaiai_unavailable
    • created_atstring · date-time
  • moderation_statestring

    approved content shows in the portal. held content waits for your team's review, and rejected content shows only to its author and your team. What your team and API keys create is always approved.

    One ofapprovedheldrejected
  • numberinteger

    The post's number in the workspace: 1, 2, 3...

  • slugstring

    Made from the title, and unique among the workspace's posts outside the trash. Former slugs still lead to the post.

    At most 90 characters

  • sourcestring

    Where the post came from: dashboard (your team, in the dashboard), api (an API key or the MCP server), portal (someone on the portal or in the widget), import (an import) or slack (made from Slack, with the command or the shortcut).

    One ofdashboardapiportalimportslack
  • statusstring
    One ofpendingreviewplannedin_progresscompletedclosed
  • tagsarray of objects

    The post's tags, sorted by name.

    Fields of each item (7)
    • idstring

      Starts with tag_

    • colorstringnullable

      The tag's color, a hex color such as #3b82f6, or null.

    • namestring

      1 to 40 characters

    • scopestring

      What the tag labels: post for posts, changelog for changelog entries.

      One ofpostchangelog
    • sourcestring

      ai if the AI chose the tag (ai_tagging), else manual.

      One ofmanualai
    • created_atstring · date-time
    • updated_atstring · date-time
  • titlestring

    1 to 200 characters

  • translationobjectnullable

    The post in the language the request asked for with language. Null without that parameter, for a post written in that language, and for one the AI hasn't translated.

    Child fields (3)
    • body_htmlstring

      The translated text, rendered as sanitized HTML like the original.

    • languagestring

      One of the seven languages the portal and Swingback's emails come in.

      One ofenfrdeesitptnl
    • titlestring
  • visibilitystring

    public for everyone. private hides the post from other customers: only your team and the post's author see it, and the author still gets notifications about it. A post on a private board is hidden from customers whatever its visibility.

    One ofpublicprivate
  • vote_countinteger

    How many votes the post has, those of the posts merged into it included. A customer who voted for both counts once.

  • created_atstring · date-time
  • updated_atstring · date-time
  • deleted_atstring · date-timenullable

    Set while the post is in the trash.

  • edited_atstring · date-timenullable

    When the post's title or text last changed, whoever changed them. Null for a post nobody edited. updated_at also changes with every vote, status change and comment that counts in comment_count.

  • status_changed_atstring · date-time

    When the post took its status: when it was created, or when its status last changed.

Example

The post object
{
  "id": "post_01h455vb4pex5vsknk084sn02q",
  "attachments": [],
  "author": {
    "id": "user_01h455vb4pex5vsknk084sn02q",
    "avatar_url": null,
    "email": "dana@example.com",
    "external_id": "u-8412",
    "kind": "user",
    "name": "Dana Kim"
  },
  "board_id": "board_01h455vb4pex5vsknk084sn02q",
  "body_html": "<p>Finance exports every report by hand.</p>",
  "body_md": "Finance exports every report by hand.",
  "comment_count": 3,
  "customer_value": 1250000,
  "language": "en",
  "merged_into_id": null,
  "moderation_flags": [],
  "moderation_state": "approved",
  "number": 42,
  "slug": "export-reports-to-csv",
  "source": "api",
  "status": "planned",
  "tags": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "scope": "post",
      "name": "Reporting",
      "color": "#3b82f6",
      "source": "manual",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "title": "Export reports to CSV",
  "translation": null,
  "visibility": "public",
  "vote_count": 17,
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z",
  "deleted_at": null,
  "edited_at": null,
  "status_changed_at": "2026-09-28T14:03:12.482Z"
}

The status change object#

Fields

  • idstring

    Starts with change_

  • actorobject
    Child fields (2)
    • idstringnullable

      The id of the account, API key, import or integration. Null for the system.

    • typestring

      Who changed the status: a team member's account, an api_key, the system, an import for history that an import brought in, or an integration when the post's GitHub or Linear issues moved it.

      One ofaccountapi_keysystemimportintegration
  • from_statusstring
    One ofpendingreviewplannedin_progresscompletedclosed
  • note_htmlstring

    The note, as HTML.

  • note_mdstring

    The note written with the change, in Markdown. Empty without one.

    At most 5,000 characters

  • post_idstring

    Starts with post_

  • to_statusstring
    One ofpendingreviewplannedin_progresscompletedclosed
  • created_atstring · date-time

Example

The status change object
{
  "id": "change_01h455vb4pex5vsknk084sn02q",
  "actor": {
    "type": "account",
    "id": "acct_01h455vb4pex5vsknk084sn02q"
  },
  "from_status": "review",
  "note_html": "<p>Planned for the March release.</p>",
  "note_md": "Planned for the March release.",
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "to_status": "planned",
  "created_at": "2026-09-28T14:03:12.482Z"
}

Fields

  • idstring

    Starts with link_

  • body_mdstring

    The requested text, until the issue exists.

  • copies_commentsboolean

    Whether a comment that anyone can see, written on the post now, would be copied to the issue. That's when the connection sends comments there, and the post is public if the destination is.

  • copies_notesboolean

    Whether an internal note written on the post now would be copied to the issue.

  • destinationobject
    Child fields (12)
    • idstring

      Starts with destination_

    • archivedboolean

      Whether it's an archived repository, or an archived or retired team. It then takes no issues.

    • descriptionstring

      What it holds, for people and for routing.

      At most 500 characters

    • enabledboolean

      Whether it takes issues.

    • goneboolean

      Whether its connection has lost access to it.

    • integration_idstring

      Starts with integration_

    • kindstring
      One ofgithub_repositorylinear_team
    • namestring

      A repository's full name, such as acme/web, or a team's name.

    • publicboolean

      Whether anyone can read it, as in a public repository. A Linear team is never public.

    • urlstring

      The destination's page on its tracker.

    • created_atstring · date-time
    • updated_atstring · date-time
  • error_codestringnullable

    Why the issue couldn't be created: issues_disabled, forbidden, repository_not_found, team_not_found, rejected, destination_unavailable, connection_stopped, or public_destination (the post stopped being public before its issue was created in a public destination, and no member confirmed it could go there).

  • issueobjectnullable

    Null until the issue exists.

    Child fields (11)
    • idstring

      Starts with issue_

    • keystring

      The issue's key on its tracker, such as #123 or ENG-123.

    • labelsarray of strings

      At most 100 items

    • leftstringnullable

      Why the issue no longer counts: deleted (on Linear, moved to the trash), transferred to a repository (or moved to a team) where the workspace takes no issues, or unreachable by its connection.

      One ofdeletedtransferredunreachable
    • statestring

      On GitHub, open or closed. On Linear, the type of the issue's workflow state: triage, backlog, unstarted, started, completed, canceled or duplicate.

    • state_namestringnullable

      On Linear, the name of the issue's workflow state, such as In Review. Null on GitHub.

    • state_reasonstringnullable

      On GitHub, why the issue was closed or reopened: completed, not_planned, duplicate or reopened.

    • statusstringnullable

      The post status that the issue's state maps to, under its connection's settings. Null when it maps to none, and for an issue that left or is a duplicate.

      One ofreviewplannedin_progresscompletedclosed
    • titlestring
    • urlstring

      The issue's page on its tracker.

    • updated_atstring · date-time

      When the issue last changed, by its tracker's clock.

  • labelsarray of strings

    The requested labels.

    At most 10 items

  • originstring

    created from the post by a member, linked to an existing issue, or created by the routing rules (rule) when the post reached a status.

    One ofcreatedlinkedrule
  • post_idstring

    The post the link was made on: this one, or one merged into it.

    Starts with post_

  • public_confirmedboolean

    Whether a member confirmed that the post can go to a public destination.

  • statestring

    creating until the requested issue exists, then linked, or failed if it couldn't be created.

    One ofcreatinglinkedfailed
  • titlestring

    The requested title, then the issue's own once it exists.

  • created_atstring · date-time
  • updated_atstring · date-time

Example

The issue link object
{
  "id": "link_01h455vb4pex5vsknk084sn02q",
  "body_md": "Finance exports every report by hand.",
  "copies_comments": true,
  "copies_notes": false,
  "destination": {
    "id": "destination_01h455vb4pex5vsknk084sn02q",
    "archived": false,
    "description": "The web app's issues.",
    "enabled": true,
    "gone": false,
    "integration_id": "integration_01h455vb4pex5vsknk084sn02q",
    "kind": "github_repository",
    "name": "acme/web",
    "public": false,
    "url": "https://github.com/acme/web",
    "created_at": "2026-09-28T14:03:12.482Z",
    "updated_at": "2026-09-28T14:03:12.482Z"
  },
  "error_code": null,
  "issue": {
    "id": "issue_01h455vb4pex5vsknk084sn02q",
    "key": "#123",
    "labels": [],
    "left": null,
    "state": "open",
    "state_name": null,
    "state_reason": null,
    "status": "planned",
    "title": "Export reports to CSV",
    "url": "https://github.com/acme/web/issues/123",
    "updated_at": "2026-09-28T14:03:12.482Z"
  },
  "labels": [],
  "origin": "created",
  "post_id": "post_01h455vb4pex5vsknk084sn02q",
  "public_confirmed": false,
  "state": "linked",
  "title": "Export reports to CSV",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z"
}

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