Changelog
Changelog entries are your team's announcements: drafts, scheduled entries or published ones. A scheduled entry is published within a minute of its time. The portal shows published entries with the posts they link; a whispered entry is published quietly, without being announced or marked unread.
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 changelog entries#
/ v1/ workspaces/ {workspace_id}/ changelogAny API key: Read or Read and write
Returns live entries, or the entries in the trash with deleted=true, sorted by the date each one shows (when it was published, is scheduled or was created), the most recent first.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
statusarray of stringsOnly the entries with any of these statuses. Repeat the parameter for each value.
Each one ofdraftscheduledpublishedAt most 3 items
tag_idarray of stringsOnly the entries with any of these tags. Repeat the parameter for each value.
At most 20 itemsEach starts with
tag_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
Responses
- 200OKA page of entries. The changelog entry objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/changelog?status=published" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"data": [
{
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "published",
"summary": "Export any report to CSV in one click.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null,
"first_published_at": "2026-09-28T14:03:12.482Z",
"publish_at": null,
"published_at": "2026-09-28T14:03:12.482Z"
}
],
"next_cursor": null,
"has_more": false
}Create a changelog entry#
/ v1/ workspaces/ {workspace_id}/ changelogAn API key with Read and write access
Creates the entry as a draft. Its authors, author_ids, are team members' account ids (acct_...): with an API key, the entry has no author unless you name some. To publish or schedule the draft, call Publish or schedule a changelog entry.
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/jsonrequiredtitlestringrequiredThe entry's title.
1 to 200 characters
body_mdstringThe entry's text, in Markdown.
At most 100,000 characters
author_idsarray of stringsThe authors, in order, as team members' account ids.
At most 10 itemsEach starts with
acct_cover_asset_idstringAn image to use as the cover, from your own uploads that aren't attached to anything yet.
Starts with
asset_post_idsarray of stringsThe posts the entry announces, in order.
At most 20 itemsEach starts with
post_summarystringPlain text, for lists, feeds and emails.
At most 500 characters
tag_idsarray of stringsTags with the
changelogscope.At most 10 itemsEach starts with
tag_whisperbooleanWhether to publish the entry quietly: it's never announced or marked unread.
Defaults to
false
Responses
- 201CreatedThe new draft entry object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST "$SWINGBACK_API/changelog" \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "CSV exports are here",
"summary": "Export any report to CSV in one click.",
"body_md": "Choose **Export → CSV**.",
"tag_ids": [
"tag_01h455vb4pex5vsknk084sn05t"
],
"author_ids": [
"acct_01h455vb4pex5vsknk084sn02q"
],
"post_ids": [
"post_01h455vb4pex5vsknk084sn02q"
]
}'{
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "draft",
"summary": "Export any report to CSV in one click.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null,
"first_published_at": null,
"publish_at": null,
"published_at": null
}Retrieve a changelog entry#
/ v1/ workspaces/ {workspace_id}/ changelog/ {changelog_entry_id}Any API key: Read or Read and write
Returns a changelog entry, live or in the trash.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_changelog_entry_idstringrequiredThe changelog entry's id.
Starts with
entry_
Responses
- 200OKThe entry object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q" {
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "published",
"summary": "Export any report to CSV in one click.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null,
"first_published_at": "2026-09-28T14:03:12.482Z",
"publish_at": null,
"published_at": "2026-09-28T14:03:12.482Z"
}Update a changelog entry#
/ v1/ workspaces/ {workspace_id}/ changelog/ {changelog_entry_id}An API key with Read and write access
Fields you don't send stay unchanged, and cover_asset_id: null removes the cover. A new title gives a new slug to an entry that was never published; a published entry keeps its slug. An entry in the trash returns 409 in_trash.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_changelog_entry_idstringrequiredThe changelog entry's id.
Starts with
entry_
Request body
application/jsonrequiredtitlestringThe entry's new title.
1 to 200 characters
body_mdstringThe entry's text, in Markdown.
At most 100,000 characters
author_idsarray of stringsThe authors, in order, as team members' account ids. An author who has left the team can stay.
At most 10 itemsEach starts with
acct_cover_asset_idstringnullableAn uploaded image to use as the cover. Null removes the cover.
Starts with
asset_post_idsarray of stringsThe posts the entry announces, in order. A new post must be live and not merged; a post that's already linked can stay, whatever happened to it since.
At most 20 itemsEach starts with
post_summarystringPlain text, for lists, feeds and emails.
At most 500 characters
tag_idsarray of stringsThe entry's tags, all with the
changelogscope, in place of the current ones. An empty list removes every tag.At most 10 itemsEach starts with
tag_whisperbooleanWhether the entry is published quietly: it's never announced or marked unread.
Responses
- 200OKThe updated entry 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 '{
"summary": "Export any report to CSV from its menu."
}' \
"$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q" {
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "published",
"summary": "Export any report to CSV from its menu.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-10-02T09:30:00.000Z",
"deleted_at": null,
"first_published_at": "2026-09-28T14:03:12.482Z",
"publish_at": null,
"published_at": "2026-09-28T14:03:12.482Z"
}Delete a changelog entry#
/ v1/ workspaces/ {workspace_id}/ changelog/ {changelog_entry_id}An API key with Read and write access
Moves the entry to the trash. It stays there for 30 days, then is deleted for good. While it's in the trash, the portal doesn't show it, and a scheduled entry isn't published. Deleting an entry that's already in the trash changes nothing.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_changelog_entry_idstringrequiredThe changelog entry's id.
Starts with
entry_
Responses
- 204No ContentThe entry is in the trash.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q" The response is 204 No Content, with no body.
Restore a changelog entry#
/ v1/ workspaces/ {workspace_id}/ changelog/ {changelog_entry_id}/ restoreAn API key with Read and write access
Takes the entry out of the trash as it was: a published entry shows again, and a scheduled one is published when it's due. If a live entry took its slug in the meantime, the restored entry gets a new one. Restoring a live entry changes nothing.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_changelog_entry_idstringrequiredThe changelog entry's id.
Starts with
entry_
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 entry object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q/restore" {
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "published",
"summary": "Export any report to CSV in one click.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-10-02T09:30:00.000Z",
"deleted_at": null,
"first_published_at": "2026-09-28T14:03:12.482Z",
"publish_at": null,
"published_at": "2026-09-28T14:03:12.482Z"
}Publish or schedule a changelog entry#
/ v1/ workspaces/ {workspace_id}/ changelog/ {changelog_entry_id}/ publicationAn API key with Read and write access
Without publish_at, publishes the entry now. Publishing a published entry again changes nothing. With publish_at, which must be in the future and within a year, schedules the entry: it's published within a minute of that time. Scheduling a published entry returns 409 already_published: unpublish it first. An entry in the trash returns 409 in_trash: restore it first.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_changelog_entry_idstringrequiredThe changelog entry's id.
Starts with
entry_
Request body
application/jsonoptionalpublish_atstring · date-timeWhen to publish the entry. Without it, the entry is published now.
Responses
- 200OKThe published or scheduled entry 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 '{
"publish_at": "2027-01-01T09:00:00.000Z"
}' \
"$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q/publication" {
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "scheduled",
"summary": "Export any report to CSV in one click.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-10-02T09:30:00.000Z",
"deleted_at": null,
"first_published_at": null,
"publish_at": "2027-01-01T09:00:00.000Z",
"published_at": null
}Unpublish a changelog entry#
/ v1/ workspaces/ {workspace_id}/ changelog/ {changelog_entry_id}/ publicationAn API key with Read and write access
Returns the entry to draft: a scheduled entry is unscheduled, and a published one leaves the portal. Unpublishing a draft changes nothing. An entry in the trash returns 409 in_trash: restore it first.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_changelog_entry_idstringrequiredThe changelog entry's id.
Starts with
entry_
Responses
- 200OKThe draft entry object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q/publication" {
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "draft",
"summary": "Export any report to CSV in one click.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-10-02T09:30:00.000Z",
"deleted_at": null,
"first_published_at": "2026-09-28T14:03:12.482Z",
"publish_at": null,
"published_at": null
}The changelog entry object#
Fields
idstringStarts with
entry_authorsarray of objectsThe team members named as the entry's authors (
author_ids).Fields of each item (3)
account_idstringStarts with
acct_avatar_urlstringnullablenamestringnullable
body_htmlstringbody_md, rendered as sanitized HTML.body_mdstringAt most 100,000 characters
coverobjectnullableThe cover image.
An asset object.
postsarray of objectsThe linked posts, in their order, as they are now.
Fields of each item (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.
slugstringMade from the title until the entry is first published. After that, it changes only if the entry comes back from the trash after another entry took its slug.
1 to 90 characters
statusstringdraft,scheduled(to be published atpublish_at) orpublished.One ofdraftscheduledpublishedsummarystringPlain text, for lists, feeds and emails.
At most 500 characters
tagsarray of objectsThe entry's tags, sorted by name.
Each item is a tag object.
titlestring1 to 200 characters
whisperbooleanWhether the entry is published quietly: it's never announced or marked unread.
created_atstring · date-timeupdated_atstring · date-timedeleted_atstring · date-timenullableSet while the entry is in the trash.
first_published_atstring · date-timenullableWhen the entry was first published.
publish_atstring · date-timenullableWhen a scheduled entry will be published.
published_atstring · date-timenullableWhen a published entry was last made public.
Example
{
"id": "entry_01h455vb4pex5vsknk084sn02q",
"authors": [
{
"account_id": "acct_01h455vb4pex5vsknk084sn02q",
"avatar_url": null,
"name": "Sam Lee"
}
],
"body_html": "<p>Choose <strong>Export → CSV</strong>.</p>",
"body_md": "Choose **Export → CSV**.",
"cover": null,
"posts": [
{
"id": "post_01h455vb4pex5vsknk084sn02q",
"merged_into_id": null,
"number": 42,
"slug": "export-reports-to-csv",
"status": "completed",
"title": "Export reports to CSV",
"visibility": "public",
"vote_count": 17,
"deleted_at": null
}
],
"slug": "csv-exports-are-here",
"status": "published",
"summary": "Export any report to CSV in one click.",
"tags": [
{
"id": "tag_01h455vb4pex5vsknk084sn05t",
"scope": "changelog",
"name": "New",
"color": "#22c55e",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z"
}
],
"title": "CSV exports are here",
"whisper": false,
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null,
"first_published_at": "2026-09-28T14:03:12.482Z",
"publish_at": null,
"published_at": "2026-09-28T14:03:12.482Z"
}