Skip to content
Swingback, home

API reference

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

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

Create a changelog draft#

POST/v1/workspaces/{workspace_id}/changelog-drafts

An 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_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
  • post_idsarray of stringsrequired

    The live posts the entry announces.

    1 to 20 itemsEach starts with post_

  • notesstring

    What you want the entry to say, as instructions for the model.

    At most 1,000 characters

Responses

  • 202
    AcceptedThe draft, while the model writes it. Returns a changelog draft object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
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."
  }'
Response · 202 Accepted
{
  "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#

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

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

    Starts with ws_

  • changelog_draft_idstringrequired

    The changelog draft's id.

    Starts with draft_

Responses

Example

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

GET/v1/workspaces/{workspace_id}/merge-suggestions

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

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

    Starts with ws_

Query parameters

  • statusstring

    Only the suggestions with this status. Defaults to pending.

    One ofpendingaccepteddismissed
  • 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/merge-suggestions" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "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#

POST/v1/workspaces/{workspace_id}/merge-suggestions/{merge_suggestion_id}/accept

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

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

    Starts with ws_

  • merge_suggestion_idstringrequired

    The merge suggestion's id.

    Starts with msug_

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

Example

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

POST/v1/workspaces/{workspace_id}/merge-suggestions/{merge_suggestion_id}/dismiss

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

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

    Starts with ws_

  • merge_suggestion_idstringrequired

    The merge suggestion's id.

    Starts with msug_

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

Example

Request
curl -X POST \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/merge-suggestions/msug_01h455vb4pex5vsknk084sn02q/dismiss"
Response · 200 OK
{
  "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

  • idstring

    Starts with draft_

  • body_mdstringnullable

    At most 100,000 characters

  • errorstringnullable

    Why 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.

  • notesstring
  • post_idsarray of strings

    Each starts with post_

  • statusstring

    pending while the model writes, then ready with the text, or failed with an error.

    One ofpendingreadyfailed
  • summarystringnullable

    At most 500 characters

  • titlestringnullable

    At most 200 characters

  • created_atstring · date-time
  • completed_atstring · date-timenullable

Example

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

  • idstring

    Starts with msug_

  • distancenumber

    How far apart the posts' meanings are, as a cosine distance: 0 means identical.

  • postobject
    Child fields (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.

  • similar_postobject
    Child fields (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.

  • statusstring

    pending until someone accepts or dismisses the suggestion.

    One ofpendingaccepteddismissed
  • created_atstring · date-time
  • decided_atstring · date-timenullable

    When the suggestion was accepted or dismissed.

Example

The merge suggestion object
{
  "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
}

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