Skip to content
Swingback, home

API reference

Roadmap

The roadmap shows posts by status, a column for each. The API returns the team's roadmap, which has every status on every board. The portal's roadmap shows only planned, in_progress and completed, on the boards you put on the roadmap.

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

Retrieve the roadmap#

GET/v1/workspaces/{workspace_id}/roadmap

Any API key: Read or Read and write

Returns a column for each status, all six by default, each with the first page of its posts: live, not merged, on every board. In completed and closed, the posts whose status changed most recently come first; the other columns sort by votes. To page through a column, pass its next_cursor to List a roadmap column's posts.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

Query parameters

  • statusarray of strings

    Only these columns. Repeat the parameter for each value.

    Each one ofpendingreviewplannedin_progresscompletedclosed

    At most 6 items

  • board_idstring

    Only the posts on this board.

    Starts with board_

  • tag_idarray of strings

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

    At most 20 itemsEach starts with tag_

  • limitinteger

    How many items to return in the page.

    From 1 to 100Defaults to 25

  • languagestring

    The 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 in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl

Responses

  • 200
    OKThe columns, in the order of the statuses. Returns a roadmap object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/roadmap?status=planned&status=in_progress"
Response · 200 OK
{
  "columns": [
    {
      "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"
        }
      ],
      "status": "planned",
      "next_cursor": null,
      "has_more": false
    },
    {
      "data": [],
      "status": "in_progress",
      "next_cursor": null,
      "has_more": false
    }
  ]
}

List a roadmap column's posts#

GET/v1/workspaces/{workspace_id}/roadmap/{status}

Any API key: Read or Read and write

Returns a page of the posts in one column of the roadmap, sorted as Retrieve the roadmap sorts them. To continue a column that Retrieve the roadmap returned, pass its next_cursor as cursor, with the same filters.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • statusstringrequired

    The column's status.

    One ofpendingreviewplannedin_progresscompletedclosed

Query parameters

  • board_idstring

    Only the posts on this board.

    Starts with board_

  • tag_idarray of strings

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

    At most 20 itemsEach starts with tag_

  • 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

  • languagestring

    The 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 in translation, and its own fields keep the original. Without this parameter, translation is null.

    One ofenfrdeesitptnl

Responses

Example

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

The roadmap object#

Fields

  • columnsarray of objects
    Fields of each item (4)
    • dataarray of objects

      Each item is a post object.

    • statusstring
      One ofpendingreviewplannedin_progresscompletedclosed
    • next_cursorstringnullable

      Pass it to List a roadmap column's posts to get the column's next page.

    • has_moreboolean

Example

The roadmap object
{
  "columns": [
    {
      "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"
        }
      ],
      "status": "pending",
      "next_cursor": null,
      "has_more": false
    }
  ]
}

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