Skip to content
Swingback, home

API reference

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

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

List boards#

GET/v1/workspaces/{workspace_id}/boards

Any API key: Read or Read and write

Returns the workspace's boards, in order of position.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

Query parameters

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

POST/v1/workspaces/{workspace_id}/boards

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

    The board's name.

    1 to 80 characters

  • colorstring

    A hex color, such as #3b82f6, stored in lowercase.

  • description_mdstring

    The board's description, in Markdown, which the portal shows with the board's posts.

    At most 2,000 characters

  • positioninteger

    Defaults to after the other boards.

    From 0 to 1,000,000

  • roadmapboolean

    Whether the board's posts appear on the portal's roadmap.

    Defaults to true

  • slugstring

    Lowercase letters, digits and hyphens, unique among the workspace's live boards.

    1 to 60 characters

  • visibilitystring

    public for everyone, or private for your team only: customers see neither the board nor its posts. Defaults to public.

    One ofpublicprivate

Responses

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

Example

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

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

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

    Starts with ws_

  • board_idstringrequired

    The board's id.

    Starts with board_

Responses

Example

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

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

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

    Starts with ws_

  • board_idstringrequired

    The board's id.

    Starts with board_

Request body

application/jsonrequired
  • namestring

    The board's new name.

    1 to 80 characters

  • colorstringnullable

    A hex color, such as #3b82f6. Null removes the color.

  • description_mdstring

    The board's description, in Markdown.

    At most 2,000 characters

  • positioninteger

    Boards are listed by position, then by id.

    From 0 to 1,000,000

  • roadmapboolean

    Whether the board's posts appear on the portal's roadmap.

  • slugstring

    Lowercase letters, digits and hyphens, unique among the workspace's live boards.

    1 to 60 characters

  • visibilitystring

    public for everyone, or private for your team only: customers see neither the board nor its posts.

    One ofpublicprivate

Responses

  • 200
    OKThe updated board 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 '{
    "name": "Ideas",
    "color": null
  }' \
  "$SWINGBACK_API/boards/board_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "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#

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

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

    Starts with ws_

  • board_idstringrequired

    The board's id.

    Starts with board_

Responses

  • 204
    No ContentThe board 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/boards/board_01h455vb4pex5vsknk084sn02q"

The response is 204 No Content, with no body.

Restore a board#

POST/v1/workspaces/{workspace_id}/boards/{board_id}/restore

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

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

    Starts with ws_

  • board_idstringrequired

    The board's id.

    Starts with board_

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

Example

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

  • idstring

    Starts with board_

  • colorstringnullable

    The board's color, a hex color such as #3b82f6, or null.

  • description_htmlstring

    description_md, rendered as sanitized HTML.

  • description_mdstring

    At most 2,000 characters

  • namestring

    1 to 80 characters

  • positioninteger

    Boards are listed by position, then by id.

  • roadmapboolean

    Whether the board's posts appear on the portal's roadmap.

  • slugstring

    Lowercase letters, digits and hyphens, unique among the workspace's live boards.

    1 to 60 characters

  • visibilitystring

    public for everyone, or private for your team only: customers see neither the board nor its posts.

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

    Set while the board is in the trash.

Example

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

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