AI
Two AI features have endpoints: changelog drafts, written from the posts you choose, and merge suggestions, the pairs of posts the model takes for duplicates when the workspace turns on ai_duplicates. The model only drafts and suggests: a draft is text for your editor, and a person or a key decides each merge.
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_..." Create a changelog draft#
/ v1/ workspaces/ {workspace_id}/ changelog-draftsAn API key with Read and write access
Has the model write a title, a summary and a Markdown body from up to 20 live posts and your notes, in the workspace's default language. The draft is written in the background: poll Retrieve a changelog draft until its status is ready. A draft is only text for your editor: nothing is created or published. Each draft the model answers counts toward the plan's monthly AI drafts (403 plan_limit_reached once they're used up). Drafts are deleted after 7 days.
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/jsonrequiredpost_idsarray of stringsrequiredThe live posts the entry announces.
1 to 20 itemsEach starts with
post_notesstringWhat you want the entry to say, as instructions for the model.
At most 1,000 characters
Responses
- 202AcceptedThe draft, while the model writes it. Returns a changelog draft object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST "$SWINGBACK_API/changelog-drafts" \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"post_ids": [
"post_01h455vb4pex5vsknk084sn02q"
],
"notes": "Mention the export menu."
}'{
"id": "draft_01h455vb4pex5vsknk084sn02q",
"body_md": null,
"error": null,
"notes": "Mention the export menu.",
"post_ids": [
"post_01h455vb4pex5vsknk084sn02q"
],
"status": "pending",
"summary": null,
"title": null,
"created_at": "2026-09-28T14:03:12.482Z",
"completed_at": null
}Retrieve a changelog draft#
/ v1/ workspaces/ {workspace_id}/ changelog-drafts/ {changelog_draft_id}Any API key: Read or Read and write
Returns a changelog draft, with its text once its status is ready.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_changelog_draft_idstringrequiredThe changelog draft's id.
Starts with
draft_
Responses
- 200OKThe draft object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/changelog-drafts/draft_01h455vb4pex5vsknk084sn02q" {
"id": "draft_01h455vb4pex5vsknk084sn02q",
"body_md": "Choose **Export → CSV**.",
"error": null,
"notes": "Mention the export menu.",
"post_ids": [
"post_01h455vb4pex5vsknk084sn02q"
],
"status": "ready",
"summary": "Export any report to CSV in one click.",
"title": "CSV exports are here",
"created_at": "2026-09-28T14:03:12.482Z",
"completed_at": "2026-09-28T14:03:12.482Z"
}List merge suggestions#
/ v1/ workspaces/ {workspace_id}/ merge-suggestionsAny API key: Read or Read and write
Returns the pairs of posts that the model took for duplicates, newest first, when the workspace turns on ai_duplicates. A pending suggestion is listed only while neither of its posts is in the trash or merged; a post on a board in the trash still counts, and accepting its suggestion returns 409 in_trash.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
statusstringOnly the suggestions with this status. Defaults to
pending.One ofpendingaccepteddismissedlimitintegerHow 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 suggestions. The merge suggestion objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/merge-suggestions" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"data": [
{
"id": "msug_01h455vb4pex5vsknk084sn02q",
"distance": 0.12,
"post": {
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "planned",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
},
"similar_post": {
"id": "post_01h455vb4pex5vsknk084sn03r",
"merged_into_id": null,
"number": 17,
"slug": "csv-export-for-reports",
"status": "review",
"title": "CSV export for reports",
"visibility": "public",
"vote_count": 9,
"deleted_at": null
},
"status": "pending",
"created_at": "2026-09-28T14:03:12.482Z",
"decided_at": null
}
],
"next_cursor": null,
"has_more": false
}Accept a merge suggestion#
/ v1/ workspaces/ {workspace_id}/ merge-suggestions/ {merge_suggestion_id}/ acceptAn API key with Read and write access
Merges the suggestion's post into its similar_post, as Merge a post does, then marks the suggestion accepted. A suggestion that was already accepted or dismissed returns 409 suggestion_decided.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_merge_suggestion_idstringrequiredThe merge suggestion's id.
Starts with
msug_
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 accepted suggestion object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/merge-suggestions/msug_01h455vb4pex5vsknk084sn02q/accept" {
"id": "msug_01h455vb4pex5vsknk084sn02q",
"distance": 0.12,
"post": {
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": "post_01h455vb4pex5vsknk084sn03r",
"number": 42,
"slug": "export-reports-to-csv",
"status": "planned",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 0,
"deleted_at": null
},
"similar_post": {
"id": "post_01h455vb4pex5vsknk084sn03r",
"merged_into_id": null,
"number": 17,
"slug": "csv-export-for-reports",
"status": "review",
"title": "CSV export for reports",
"visibility": "public",
"vote_count": 24,
"deleted_at": null
},
"status": "accepted",
"created_at": "2026-09-28T14:03:12.482Z",
"decided_at": "2026-10-02T09:30:00.000Z"
}Dismiss a merge suggestion#
/ v1/ workspaces/ {workspace_id}/ merge-suggestions/ {merge_suggestion_id}/ dismissAn API key with Read and write access
Dismisses the suggestion, so the pair isn't suggested again. A suggestion that was already accepted or dismissed returns 409 suggestion_decided.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_merge_suggestion_idstringrequiredThe merge suggestion's id.
Starts with
msug_
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 dismissed suggestion object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/merge-suggestions/msug_01h455vb4pex5vsknk084sn02q/dismiss" {
"id": "msug_01h455vb4pex5vsknk084sn02q",
"distance": 0.12,
"post": {
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "planned",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
},
"similar_post": {
"id": "post_01h455vb4pex5vsknk084sn03r",
"merged_into_id": null,
"number": 17,
"slug": "csv-export-for-reports",
"status": "review",
"title": "CSV export for reports",
"visibility": "public",
"vote_count": 9,
"deleted_at": null
},
"status": "dismissed",
"created_at": "2026-09-28T14:03:12.482Z",
"decided_at": "2026-10-02T09:30:00.000Z"
}The changelog draft object#
Fields
idstringStarts with
draft_body_mdstringnullableAt most 100,000 characters
errorstringnullableWhy the draft failed:
quota(the plan's AI drafts are used up for the month),budget(the AI is paused until the next day),refused(the model declined), or another reason.notesstringpost_idsarray of stringsEach starts with
post_statusstringpendingwhile the model writes, thenreadywith the text, orfailedwith anerror.One ofpendingreadyfailedsummarystringnullableAt most 500 characters
titlestringnullableAt most 200 characters
created_atstring · date-timecompleted_atstring · date-timenullable
Example
{
"id": "draft_01h455vb4pex5vsknk084sn02q",
"body_md": "Choose **Export → CSV**.",
"error": null,
"notes": "Mention the export menu.",
"post_ids": [
"post_01h455vb4pex5vsknk084sn02q"
],
"status": "ready",
"summary": "Export any report to CSV in one click.",
"title": "CSV exports are here",
"created_at": "2026-09-28T14:03:12.482Z",
"completed_at": "2026-09-28T14:03:12.482Z"
}The merge suggestion object#
Two posts that the model took for duplicates. post is the newer one, and accepting the suggestion merges it into similar_post.
Fields
idstringStarts with
msug_distancenumberHow far apart the posts' meanings are, as a cosine distance: 0 means identical.
postobjectChild fields (9)
idstringStarts with
post_merged_into_idstringnullableThe post this one was merged into, which the portal shows instead.
Starts with
post_numberintegerslugstringThe post's address on the portal, made from its title. A new title gives it a new one, and the old addresses lead to it.
1 to 90 characters
statusstringOne ofpendingreviewplannedin_progresscompletedclosedtitlestringvisibilitystringpublic, orprivate: only your team and the post's author see it.One ofpublicprivatevote_countintegerdeleted_atstring · date-timenullableSet while the post is in the trash.
similar_postobjectChild fields (9)
idstringStarts with
post_merged_into_idstringnullableThe post this one was merged into, which the portal shows instead.
Starts with
post_numberintegerslugstringThe post's address on the portal, made from its title. A new title gives it a new one, and the old addresses lead to it.
1 to 90 characters
statusstringOne ofpendingreviewplannedin_progresscompletedclosedtitlestringvisibilitystringpublic, orprivate: only your team and the post's author see it.One ofpublicprivatevote_countintegerdeleted_atstring · date-timenullableSet while the post is in the trash.
statusstringpendinguntil someone accepts or dismisses the suggestion.One ofpendingaccepteddismissedcreated_atstring · date-timedecided_atstring · date-timenullableWhen the suggestion was accepted or dismissed.
Example
{
"id": "msug_01h455vb4pex5vsknk084sn02q",
"distance": 0.12,
"post": {
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "planned",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
},
"similar_post": {
"id": "post_01h455vb4pex5vsknk084sn03r",
"merged_into_id": null,
"number": 17,
"slug": "csv-export-for-reports",
"status": "review",
"title": "CSV export for reports",
"visibility": "public",
"vote_count": 9,
"deleted_at": null
},
"status": "pending",
"created_at": "2026-09-28T14:03:12.482Z",
"decided_at": null
}