Boards
Boards group posts by theme, such as feature requests or bugs. A board is public, or private to your team. When you delete a board, it goes to the trash with its posts, and you can restore it from there.
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 boards#
/ v1/ workspaces/ {workspace_id}/ boardsAny API key: Read or Read and write
Returns the workspace's boards, in order of position.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
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 boards. The board objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/boards" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"data": [
{
"id": "board_01h455vb4pex5vsknk084sn02q",
"color": "#3b82f6",
"description_html": "<p>Ideas for what to build next.</p>",
"description_md": "Ideas for what to build next.",
"name": "Feature requests",
"position": 1,
"roadmap": true,
"slug": "feature-requests",
"visibility": "public",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null
}
],
"next_cursor": null,
"has_more": false
}Create a board#
/ v1/ workspaces/ {workspace_id}/ boardsAn API key with Read and write access
If you send no slug, one is made from the name. A slug that another live board uses returns 409 slug_taken. The plan sets how many boards you can have and whether they can be private (403 plan_limit_reached or feature_not_in_plan).
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/jsonrequirednamestringrequiredThe board's name.
1 to 80 characters
colorstringA hex color, such as
#3b82f6, stored in lowercase.description_mdstringThe board's description, in Markdown, which the portal shows with the board's posts.
At most 2,000 characters
positionintegerDefaults to after the other boards.
From 0 to 1,000,000
roadmapbooleanWhether the board's posts appear on the portal's roadmap.
Defaults to
trueslugstringLowercase letters, digits and hyphens, unique among the workspace's live boards.
1 to 60 characters
visibilitystringpublicfor everyone, orprivatefor your team only: customers see neither the board nor its posts. Defaults topublic.One ofpublicprivate
Responses
- 201CreatedThe new board object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST "$SWINGBACK_API/boards" \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Feature requests",
"description_md": "Ideas for what to build next.",
"color": "#3b82f6",
"visibility": "public"
}'{
"id": "board_01h455vb4pex5vsknk084sn02q",
"color": "#3b82f6",
"description_html": "<p>Ideas for what to build next.</p>",
"description_md": "Ideas for what to build next.",
"name": "Feature requests",
"position": 1,
"roadmap": true,
"slug": "feature-requests",
"visibility": "public",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null
}Retrieve a board#
/ v1/ workspaces/ {workspace_id}/ boards/ {board_id}Any API key: Read or Read and write
Returns a board, live or in the trash.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_board_idstringrequiredThe board's id.
Starts with
board_
Responses
- 200OKThe board object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/boards/board_01h455vb4pex5vsknk084sn02q" {
"id": "board_01h455vb4pex5vsknk084sn02q",
"color": "#3b82f6",
"description_html": "<p>Ideas for what to build next.</p>",
"description_md": "Ideas for what to build next.",
"name": "Feature requests",
"position": 1,
"roadmap": true,
"slug": "feature-requests",
"visibility": "public",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null
}Update a board#
/ v1/ workspaces/ {workspace_id}/ boards/ {board_id}An API key with Read and write access
Fields you don't send stay unchanged, and a null color removes the color. A board in the trash returns 409 in_trash.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_board_idstringrequiredThe board's id.
Starts with
board_
Request body
application/jsonrequirednamestringThe board's new name.
1 to 80 characters
colorstringnullableA hex color, such as
#3b82f6. Null removes the color.description_mdstringThe board's description, in Markdown.
At most 2,000 characters
positionintegerBoards are listed by position, then by id.
From 0 to 1,000,000
roadmapbooleanWhether the board's posts appear on the portal's roadmap.
slugstringLowercase letters, digits and hyphens, unique among the workspace's live boards.
1 to 60 characters
visibilitystringpublicfor everyone, orprivatefor your team only: customers see neither the board nor its posts.One ofpublicprivate
Responses
- 200OKThe updated board 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 '{
"name": "Ideas",
"color": null
}' \
"$SWINGBACK_API/boards/board_01h455vb4pex5vsknk084sn02q" {
"id": "board_01h455vb4pex5vsknk084sn02q",
"color": null,
"description_html": "<p>Ideas for what to build next.</p>",
"description_md": "Ideas for what to build next.",
"name": "Ideas",
"position": 1,
"roadmap": true,
"slug": "feature-requests",
"visibility": "public",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-10-02T09:30:00.000Z",
"deleted_at": null
}Delete a board#
/ v1/ workspaces/ {workspace_id}/ boards/ {board_id}An API key with Read and write access
Moves the board and its posts to the trash. They stay there for 30 days, then are deleted for good. Deleting a board that's already in the trash changes nothing.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_board_idstringrequiredThe board's id.
Starts with
board_
Responses
- 204No ContentThe board is in the trash.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X DELETE \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/boards/board_01h455vb4pex5vsknk084sn02q" The response is 204 No Content, with no body.
Restore a board#
/ v1/ workspaces/ {workspace_id}/ boards/ {board_id}/ restoreAn API key with Read and write access
Takes the board and its posts out of the trash. If a live board took its slug in the meantime, the restored board gets a new one. The plan's board limit and private boards apply as when creating a board. Restoring a live board changes nothing.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_board_idstringrequiredThe board's id.
Starts with
board_
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 board object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
"$SWINGBACK_API/boards/board_01h455vb4pex5vsknk084sn02q/restore" {
"id": "board_01h455vb4pex5vsknk084sn02q",
"color": "#3b82f6",
"description_html": "<p>Ideas for what to build next.</p>",
"description_md": "Ideas for what to build next.",
"name": "Feature requests",
"position": 1,
"roadmap": true,
"slug": "feature-requests",
"visibility": "public",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-10-02T09:30:00.000Z",
"deleted_at": null
}The board object#
Fields
idstringStarts with
board_colorstringnullableThe board's color, a hex color such as
#3b82f6, or null.description_htmlstringdescription_md, rendered as sanitized HTML.description_mdstringAt most 2,000 characters
namestring1 to 80 characters
positionintegerBoards are listed by position, then by id.
roadmapbooleanWhether the board's posts appear on the portal's roadmap.
slugstringLowercase letters, digits and hyphens, unique among the workspace's live boards.
1 to 60 characters
visibilitystringpublicfor everyone, orprivatefor your team only: customers see neither the board nor its posts.One ofpublicprivatecreated_atstring · date-timeupdated_atstring · date-timedeleted_atstring · date-timenullableSet while the board is in the trash.
Example
{
"id": "board_01h455vb4pex5vsknk084sn02q",
"color": "#3b82f6",
"description_html": "<p>Ideas for what to build next.</p>",
"description_md": "Ideas for what to build next.",
"name": "Feature requests",
"position": 1,
"roadmap": true,
"slug": "feature-requests",
"visibility": "public",
"created_at": "2026-09-28T14:03:12.482Z",
"updated_at": "2026-09-28T14:03:12.482Z",
"deleted_at": null
}