Skip to content
Swingback, home

API reference

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

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

List changelog entries#

GET/v1/workspaces/{workspace_id}/changelog

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

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

    Starts with ws_

Query parameters

  • statusarray of strings

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

    Each one ofdraftscheduledpublished

    At most 3 items

  • tag_idarray of strings

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

    At most 20 itemsEach starts with tag_

  • 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

Responses

Example

Request
curl "$SWINGBACK_API/changelog?status=published" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "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#

POST/v1/workspaces/{workspace_id}/changelog

An 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_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
  • titlestringrequired

    The entry's title.

    1 to 200 characters

  • body_mdstring

    The entry's text, in Markdown.

    At most 100,000 characters

  • author_idsarray of strings

    The authors, in order, as team members' account ids.

    At most 10 itemsEach starts with acct_

  • cover_asset_idstring

    An image to use as the cover, from your own uploads that aren't attached to anything yet.

    Starts with asset_

  • post_idsarray of strings

    The posts the entry announces, in order.

    At most 20 itemsEach starts with post_

  • summarystring

    Plain text, for lists, feeds and emails.

    At most 500 characters

  • tag_idsarray of strings

    Tags with the changelog scope.

    At most 10 itemsEach starts with tag_

  • whisperboolean

    Whether to publish the entry quietly: it's never announced or marked unread.

    Defaults to false

Responses

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

Example

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

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

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

    Starts with ws_

  • changelog_entry_idstringrequired

    The changelog entry's id.

    Starts with entry_

Responses

Example

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

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

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

    Starts with ws_

  • changelog_entry_idstringrequired

    The changelog entry's id.

    Starts with entry_

Request body

application/jsonrequired
  • titlestring

    The entry's new title.

    1 to 200 characters

  • body_mdstring

    The entry's text, in Markdown.

    At most 100,000 characters

  • author_idsarray of strings

    The 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_idstringnullable

    An uploaded image to use as the cover. Null removes the cover.

    Starts with asset_

  • post_idsarray of strings

    The 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_

  • summarystring

    Plain text, for lists, feeds and emails.

    At most 500 characters

  • tag_idsarray of strings

    The entry's tags, all with the changelog scope, in place of the current ones. An empty list removes every tag.

    At most 10 itemsEach starts with tag_

  • whisperboolean

    Whether the entry is published quietly: it's never announced or marked unread.

Responses

  • 200
    OKThe updated entry 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 '{
    "summary": "Export any report to CSV from its menu."
  }' \
  "$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "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#

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

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

    Starts with ws_

  • changelog_entry_idstringrequired

    The changelog entry's id.

    Starts with entry_

Responses

  • 204
    No ContentThe entry 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/changelog/entry_01h455vb4pex5vsknk084sn02q"

The response is 204 No Content, with no body.

Restore a changelog entry#

POST/v1/workspaces/{workspace_id}/changelog/{changelog_entry_id}/restore

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

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

    Starts with ws_

  • changelog_entry_idstringrequired

    The changelog entry's id.

    Starts with entry_

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 entry object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q/restore"
Response · 200 OK
{
  "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#

PUT/v1/workspaces/{workspace_id}/changelog/{changelog_entry_id}/publication

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

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

    Starts with ws_

  • changelog_entry_idstringrequired

    The changelog entry's id.

    Starts with entry_

Request body

application/jsonoptional
  • publish_atstring · date-time

    When to publish the entry. Without it, the entry is published now.

Responses

  • 200
    OKThe published or scheduled entry 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 '{
    "publish_at": "2027-01-01T09:00:00.000Z"
  }' \
  "$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q/publication"
Response · 200 OK
{
  "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#

DELETE/v1/workspaces/{workspace_id}/changelog/{changelog_entry_id}/publication

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

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

    Starts with ws_

  • changelog_entry_idstringrequired

    The changelog entry's id.

    Starts with entry_

Responses

  • 200
    OKThe draft entry object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/changelog/entry_01h455vb4pex5vsknk084sn02q/publication"
Response · 200 OK
{
  "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

  • idstring

    Starts with entry_

  • authorsarray of objects

    The team members named as the entry's authors (author_ids).

    Fields of each item (3)
    • account_idstring

      Starts with acct_

    • avatar_urlstringnullable
    • namestringnullable
  • body_htmlstring

    body_md, rendered as sanitized HTML.

  • body_mdstring

    At most 100,000 characters

  • coverobjectnullable

    The cover image.

    An asset object.

  • postsarray of objects

    The linked posts, in their order, as they are now.

    Fields of each item (9)
    • idstring

      Starts with post_

    • merged_into_idstringnullable

      The post this one was merged into, which the portal shows instead.

      Starts with post_

    • numberinteger
    • slugstring

      The 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

    • statusstring
      One ofpendingreviewplannedin_progresscompletedclosed
    • titlestring
    • visibilitystring

      public, or private: only your team and the post's author see it.

      One ofpublicprivate
    • vote_countinteger
    • deleted_atstring · date-timenullable

      Set while the post is in the trash.

  • slugstring

    Made 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

  • statusstring

    draft, scheduled (to be published at publish_at) or published.

    One ofdraftscheduledpublished
  • summarystring

    Plain text, for lists, feeds and emails.

    At most 500 characters

  • tagsarray of objects

    The entry's tags, sorted by name.

    Each item is a tag object.

  • titlestring

    1 to 200 characters

  • whisperboolean

    Whether the entry is published quietly: it's never announced or marked unread.

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

    Set while the entry is in the trash.

  • first_published_atstring · date-timenullable

    When the entry was first published.

  • publish_atstring · date-timenullable

    When a scheduled entry will be published.

  • published_atstring · date-timenullable

    When a published entry was last made public.

Example

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

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