Skip to content
Swingback, home

API reference

Tags

Tags label posts or changelog entries, as their scope says. Names are unique within a scope, whatever their case.

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 tags#

GET/v1/workspaces/{workspace_id}/tags

Any API key: Read or Read and write

Returns the workspace's tags, sorted by name.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

Query parameters

  • scopestring

    Only the tags of this scope.

    One ofpostchangelog
  • 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/tags?scope=post" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "data": [
    {
      "id": "tag_01h455vb4pex5vsknk084sn02q",
      "color": "#3b82f6",
      "name": "Reporting",
      "scope": "post",
      "created_at": "2026-09-28T14:03:12.482Z",
      "updated_at": "2026-09-28T14:03:12.482Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Create a tag#

POST/v1/workspaces/{workspace_id}/tags

An API key with Read and write access

Names are unique within a scope, ignoring case: a name that's taken returns 409 tag_name_taken.

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 tag's name, unique in its scope, ignoring case.

    1 to 40 characters

  • scopestringrequired

    What the tag labels: post for posts, changelog for changelog entries.

    One ofpostchangelog
  • colorstring

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

Responses

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

Example

Request
curl -X POST "$SWINGBACK_API/tags" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "post",
    "name": "Reporting",
    "color": "#3b82f6"
  }'
Response · 201 Created
{
  "id": "tag_01h455vb4pex5vsknk084sn02q",
  "color": "#3b82f6",
  "name": "Reporting",
  "scope": "post",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z"
}

Retrieve a tag#

GET/v1/workspaces/{workspace_id}/tags/{tag_id}

Any API key: Read or Read and write

Returns a tag, for posts or for changelog entries.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • tag_idstringrequired

    The tag's id.

    Starts with tag_

Responses

  • 200
    OKThe tag object.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl "$SWINGBACK_API/tags/tag_01h455vb4pex5vsknk084sn02q" \
  -H "Authorization: Bearer $SWINGBACK_API_KEY"
Response · 200 OK
{
  "id": "tag_01h455vb4pex5vsknk084sn02q",
  "color": "#3b82f6",
  "name": "Reporting",
  "scope": "post",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z"
}

Update a tag#

PATCH/v1/workspaces/{workspace_id}/tags/{tag_id}

An API key with Read and write access

Renames or recolors a tag. Fields you don't send stay unchanged, and a null color removes the color.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • tag_idstringrequired

    The tag's id.

    Starts with tag_

Request body

application/jsonrequired
  • namestring

    The tag's new name, unique in its scope, ignoring case.

    1 to 40 characters

  • colorstringnullable

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

Responses

  • 200
    OKThe updated tag 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": "Reports"
  }' \
  "$SWINGBACK_API/tags/tag_01h455vb4pex5vsknk084sn02q"
Response · 200 OK
{
  "id": "tag_01h455vb4pex5vsknk084sn02q",
  "color": "#3b82f6",
  "name": "Reports",
  "scope": "post",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-10-02T09:30:00.000Z"
}

Delete a tag#

DELETE/v1/workspaces/{workspace_id}/tags/{tag_id}

An API key with Read and write access

Removes the tag from every post or changelog entry it labels.

Path parameters

  • workspace_idstringrequired

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

    Starts with ws_

  • tag_idstringrequired

    The tag's id.

    Starts with tag_

Responses

  • 204
    No ContentThe tag was deleted.
  • 4xxErrorProblem details with a stable code: see Errors.

Example

Request
curl -X DELETE \
  -H "Authorization: Bearer $SWINGBACK_API_KEY" \
  "$SWINGBACK_API/tags/tag_01h455vb4pex5vsknk084sn02q"

The response is 204 No Content, with no body.

The tag object#

Fields

  • idstring

    Starts with tag_

  • colorstringnullable

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

  • namestring

    1 to 40 characters

  • scopestring

    What the tag labels: post for posts, changelog for changelog entries.

    One ofpostchangelog
  • created_atstring · date-time
  • updated_atstring · date-time

Example

The tag object
{
  "id": "tag_01h455vb4pex5vsknk084sn02q",
  "color": "#3b82f6",
  "name": "Reporting",
  "scope": "post",
  "created_at": "2026-09-28T14:03:12.482Z",
  "updated_at": "2026-09-28T14:03:12.482Z"
}

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