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):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." List posts#
/ v1/ workspaces/ {workspace_id}/ postsAny 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
sortstringDefaults to
newest, or torelevancewithq. A search can only sort byrelevance, andrelevanceneedsq.One ofnewestoldesttoptrendingrelevancecustomer_valueqstringThe words to search for.
1 to 200 characters
board_idstringOnly the posts on this board.
Starts with
board_statusarray of stringsOnly the posts with any of these statuses. Repeat the parameter for each value.
Each one ofpendingreviewplannedin_progresscompletedclosedAt most 6 items
tag_idarray of stringsOnly the posts with any of these tags. Repeat the parameter for each value.
At most 20 itemsEach starts with
tag_author_idstringOnly the posts by this end user.
Starts with
user_company_idstringOnly the posts that members of this company vote for.
Starts with
company_visibilitystringOnly the public posts, or only the private ones.
One ofpublicprivatemoderation_statearray of stringsOnly the posts in any of these moderation states. Repeat the parameter for each value.
Each one ofapprovedheldrejectedAt most 3 items
deletedbooleanReturn the items in the trash instead of the live ones.
Defaults to
falselimitintegerHow 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
languagestringThe 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 intranslation, and its own fields keep the original. Without this parameter,translationis null.One ofenfrdeesitptnl
Responses
- 200OKA page of posts. The post 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?status=planned&sort=top&limit=10" {
"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#
/ v1/ workspaces/ {workspace_id}/ postsAn 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
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/jsonrequiredA new post. status defaults to pending, and visibility to public.
authorobjectrequiredWho the post is from: an existing end user by
id, or a customer byexternal_idoremail, who's created if new. The author follows the post.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
board_idstringrequiredThe board to post on. It can't be in the trash.
Starts with
board_titlestringrequiredThe post's title.
1 to 200 characters
body_mdstringThe post's text, in Markdown.
At most 20,000 characters
asset_idsarray of stringsUploaded images to attach, in order, from your own uploads that aren't attached to anything yet.
At most 4 itemsEach starts with
asset_statusstringThe post's status. Defaults to
pending.One ofpendingreviewplannedin_progresscompletedclosedtag_idsarray of stringsTags with the
postscope.At most 10 itemsEach starts with
tag_visibilitystringpublicfor everyone, the default.privatehides 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
- 201CreatedThe new post object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
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"
}
}'{
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Query parameters
languagestringThe 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 intranslation, and its own fields keep the original. Without this parameter,translationis null.One ofenfrdeesitptnl
Responses
- 200OKThe post object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q" {
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Request body
application/jsonrequiredtitlestringThe post's new title. The slug follows it, and former slugs still lead to the post.
1 to 200 characters
body_mdstringThe post's new text, in Markdown.
At most 20,000 characters
asset_idsarray of stringsThe 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_idstringThe board to move the post to. It can't be in the trash.
Starts with
board_visibilitystringpublicfor everyone.privatehides 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
- 200OKThe updated post object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
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" {
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Responses
- 204No ContentThe post is in the trash.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
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#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ restoreAn 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_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
Responses
- 200OKThe restored post object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/restore" {
"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#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ mergeAn 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_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/jsonrequiredinto_post_idstringrequiredThe post to merge this one into.
Starts with
post_
Responses
- 200OKThe target post 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 '{
"into_post_id": "post_01h455vb4pex5vsknk084sn03r"
}' \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/merge" {
"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#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ unmergeAn 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_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
Responses
- 200OKThe unmerged post object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/unmerge" {
"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#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ statusAn 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_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/jsonrequiredstatusstringrequiredThe post's new status.
One ofpendingreviewplannedin_progresscompletedclosednote_mdstringYour team's note about the change, in Markdown.
At most 5,000 characters
sync_issuesbooleanWhether the post's linked issues follow the change. False leaves them as they are.
Defaults to
true
Responses
- 200OKThe updated post 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 '{
"status": "completed",
"note_md": "Shipped in version 2.4."
}' \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/status" {
"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#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ status-changesAny API key: Read or Read and write
Returns the post's status history, newest 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 status changes. The status change 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/status-changes" {
"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#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ tagsAn 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Request body
application/jsonrequiredtag_idsarray of stringsrequiredThe post's new tags, all with the
postscope. An empty list removes every tag.At most 10 itemsEach starts with
tag_
Responses
- 200OKThe updated post object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
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" {
"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#
/ v1/ workspaces/ {workspace_id}/ posts/ {post_id}/ issue-linksAny 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_post_idstringrequiredThe post's id.
Starts with
post_
Responses
- 200OKThe post's issue links. The issue link objects are all in
data. - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/posts/post_01h455vb4pex5vsknk084sn02q/issue-links" {
"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
idstringStarts with
post_attachmentsarray of objectsEach item is an asset object.
authorobjectChild fields (6)
idstringStarts with
user_avatar_urlstringnullableemailstring · emailnullableexternal_idstringnullablekindstringuserfor a customer,teamfor the team's own rows (a team member acting as themselves, an issue tracker's connection, or an imported team author), andguestfor someone who wrote in the portal without signing in.One ofuserteamguestnamestringnullable
board_idstringStarts with
board_body_htmlstringbody_md, rendered as sanitized HTML.body_mdstringAt most 20,000 characters
comment_countintegerHow many live, public, approved comments the post has.
customer_valueintegerThe sum of the values of the distinct companies whose members vote for the post.
At least 0
languagestringnullableThe 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_idstringnullableThe post this one was merged into.
Starts with
post_moderation_flagsarray of objectsWhy the post is held. Empty once your team has decided.
Fields of each item (3)
detailstringWhat the reason found: the kinds of data for
sensitive_data, separated by commas; the category forai; why forai_unavailable. Empty for the other reasons.At most 200 characters
reasonstringapproval: the workspace reviews this kind of content first.sensitive_data: a card number, an IBAN, a key or a token (detaillists the kinds).links: more than 3 links.duplicate: the author wrote the same text in the last 24 hours.ai: the AI moderation found whatdetailnames (spam,abuse,sexual,violenceorpersonal_data).ai_unavailable: a guest's text that the AI moderation couldn't judge (detailsays why).One ofapprovalsensitive_datalinksduplicateaiai_unavailablecreated_atstring · date-time
moderation_statestringapprovedcontent shows in the portal.heldcontent waits for your team's review, andrejectedcontent shows only to its author and your team. What your team and API keys create is always approved.One ofapprovedheldrejectednumberintegerThe post's number in the workspace: 1, 2, 3...
slugstringMade from the title, and unique among the workspace's posts outside the trash. Former slugs still lead to the post.
At most 90 characters
sourcestringWhere 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) orslack(made from Slack, with the command or the shortcut).One ofdashboardapiportalimportslackstatusstringOne ofpendingreviewplannedin_progresscompletedclosedtagsarray of objectsThe post's tags, sorted by name.
Fields of each item (7)
idstringStarts with
tag_colorstringnullableThe tag's color, a hex color such as
#3b82f6, or null.namestring1 to 40 characters
scopestringWhat the tag labels:
postfor posts,changelogfor changelog entries.One ofpostchangelogsourcestringaiif the AI chose the tag (ai_tagging), elsemanual.One ofmanualaicreated_atstring · date-timeupdated_atstring · date-time
titlestring1 to 200 characters
translationobjectnullableThe 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_htmlstringThe translated text, rendered as sanitized HTML like the original.
languagestringOne of the seven languages the portal and Swingback's emails come in.
One ofenfrdeesitptnltitlestring
visibilitystringpublicfor everyone.privatehides 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 ofpublicprivatevote_countintegerHow many votes the post has, those of the posts merged into it included. A customer who voted for both counts once.
created_atstring · date-timeupdated_atstring · date-timedeleted_atstring · date-timenullableSet while the post is in the trash.
edited_atstring · date-timenullableWhen the post's title or text last changed, whoever changed them. Null for a post nobody edited.
updated_atalso changes with every vote, status change and comment that counts incomment_count.status_changed_atstring · date-timeWhen the post took its status: when it was created, or when its status last changed.
Example
{
"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
idstringStarts with
change_actorobjectChild fields (2)
idstringnullableThe id of the account, API key, import or integration. Null for the system.
typestringWho changed the status: a team member's
account, anapi_key, thesystem, animportfor history that an import brought in, or anintegrationwhen the post's GitHub or Linear issues moved it.One ofaccountapi_keysystemimportintegration
from_statusstringOne ofpendingreviewplannedin_progresscompletedclosednote_htmlstringThe note, as HTML.
note_mdstringThe note written with the change, in Markdown. Empty without one.
At most 5,000 characters
post_idstringStarts with
post_to_statusstringOne ofpendingreviewplannedin_progresscompletedclosedcreated_atstring · date-time
Example
{
"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"
}The issue link object#
Fields
idstringStarts with
link_body_mdstringThe requested text, until the issue exists.
copies_commentsbooleanWhether 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_notesbooleanWhether an internal note written on the post now would be copied to the issue.
destinationobjectChild fields (12)
idstringStarts with
destination_archivedbooleanWhether it's an archived repository, or an archived or retired team. It then takes no issues.
descriptionstringWhat it holds, for people and for routing.
At most 500 characters
enabledbooleanWhether it takes issues.
gonebooleanWhether its connection has lost access to it.
integration_idstringStarts with
integration_kindstringOne ofgithub_repositorylinear_teamnamestringA repository's full name, such as
acme/web, or a team's name.publicbooleanWhether anyone can read it, as in a public repository. A Linear team is never public.
urlstringThe destination's page on its tracker.
created_atstring · date-timeupdated_atstring · date-time
error_codestringnullableWhy the issue couldn't be created:
issues_disabled,forbidden,repository_not_found,team_not_found,rejected,destination_unavailable,connection_stopped, orpublic_destination(the post stopped being public before its issue was created in a public destination, and no member confirmed it could go there).issueobjectnullableNull until the issue exists.
Child fields (11)
idstringStarts with
issue_keystringThe issue's key on its tracker, such as
#123orENG-123.labelsarray of stringsAt most 100 items
leftstringnullableWhy the issue no longer counts:
deleted(on Linear, moved to the trash),transferredto a repository (or moved to a team) where the workspace takes no issues, orunreachableby its connection.One ofdeletedtransferredunreachablestatestringOn GitHub,
openorclosed. On Linear, the type of the issue's workflow state:triage,backlog,unstarted,started,completed,canceledorduplicate.state_namestringnullableOn Linear, the name of the issue's workflow state, such as
In Review. Null on GitHub.state_reasonstringnullableOn GitHub, why the issue was closed or reopened:
completed,not_planned,duplicateorreopened.statusstringnullableThe 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
leftor is a duplicate.One ofreviewplannedin_progresscompletedclosedtitlestringurlstringThe issue's page on its tracker.
updated_atstring · date-timeWhen the issue last changed, by its tracker's clock.
labelsarray of stringsThe requested labels.
At most 10 items
originstringcreatedfrom the post by a member,linkedto an existing issue, or created by the routing rules (rule) when the post reached a status.One ofcreatedlinkedrulepost_idstringThe post the link was made on: this one, or one merged into it.
Starts with
post_public_confirmedbooleanWhether a member confirmed that the post can go to a public destination.
statestringcreatinguntil the requested issue exists, thenlinked, orfailedif it couldn't be created.One ofcreatinglinkedfailedtitlestringThe requested title, then the issue's own once it exists.
created_atstring · date-timeupdated_atstring · date-time
Example
{
"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"
}