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):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." Retrieve the roadmap#
/ v1/ workspaces/ {workspace_id}/ roadmapAny 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
statusarray of stringsOnly these columns. Repeat the parameter for each value.
Each one ofpendingreviewplannedin_progresscompletedclosedAt most 6 items
board_idstringOnly the posts on this board.
Starts with
board_tag_idarray of stringsOnly the posts with any of these tags. Repeat the parameter for each value.
At most 20 itemsEach starts with
tag_limitintegerHow many items to return in the page.
From 1 to 100Defaults to
25languagestringThe 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 intranslation, and its own fields keep the original. Without this parameter,translationis null.One ofenfrdeesitptnl
Responses
- 200OKThe columns, in the order of the statuses. Returns a roadmap object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/roadmap?status=planned&status=in_progress" {
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_statusstringrequiredThe column's status.
One ofpendingreviewplannedin_progresscompletedclosed
Query parameters
board_idstringOnly the posts on this board.
Starts with
board_tag_idarray of stringsOnly the posts with any of these tags. Repeat the parameter for each value.
At most 20 itemsEach starts with
tag_limitintegerHow 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
languagestringThe 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 intranslation, and its own fields keep the original. Without this parameter,translationis null.One ofenfrdeesitptnl
Responses
- 200OKA page of posts. The post objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/roadmap/planned" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"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 objectsFields of each item (4)
dataarray of objectsEach item is a post object.
statusstringOne ofpendingreviewplannedin_progresscompletedclosednext_cursorstringnullablePass it to List a roadmap column's posts to get the column's next page.
has_moreboolean
Example
{
"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
}
]
}