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):
export SWINGBACK_API_KEY="s_live_..."
export SWINGBACK_API="https://api.swingback.dev/v1/workspaces/ws_..." List tags#
/ v1/ workspaces/ {workspace_id}/ tagsAny API key: Read or Read and write
Returns the workspace's tags, sorted by name.
Path parameters
workspace_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_
Query parameters
scopestringOnly the tags of this scope.
One ofpostchangeloglimitintegerHow 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 tags. The tag objects are in
data(see Pagination). - 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/tags?scope=post" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"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#
/ v1/ workspaces/ {workspace_id}/ tagsAn 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_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 tag's name, unique in its scope, ignoring case.
1 to 40 characters
scopestringrequiredWhat the tag labels:
postfor posts,changelogfor changelog entries.One ofpostchangelogcolorstringA hex color, such as
#3b82f6, stored in lowercase.
Responses
- 201CreatedThe new tag object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl -X POST "$SWINGBACK_API/tags" \
-H "Authorization: Bearer $SWINGBACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"scope": "post",
"name": "Reporting",
"color": "#3b82f6"
}'{
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_tag_idstringrequiredThe tag's id.
Starts with
tag_
Responses
- 200OKThe tag object.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
curl "$SWINGBACK_API/tags/tag_01h455vb4pex5vsknk084sn02q" \
-H "Authorization: Bearer $SWINGBACK_API_KEY"{
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_tag_idstringrequiredThe tag's id.
Starts with
tag_
Request body
application/jsonrequirednamestringThe tag's new name, unique in its scope, ignoring case.
1 to 40 characters
colorstringnullableA hex color, such as
#3b82f6. Null removes the color.
Responses
- 200OKThe updated tag 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": "Reports"
}' \
"$SWINGBACK_API/tags/tag_01h455vb4pex5vsknk084sn02q" {
"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#
/ 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_idstringrequiredYour workspace's id, shown under Settings → Sign-in.
Starts with
ws_tag_idstringrequiredThe tag's id.
Starts with
tag_
Responses
- 204No ContentThe tag was deleted.
- 4xxErrorProblem details with a stable
code: see Errors.
Example
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
idstringStarts with
tag_colorstringnullableThe tag's color, a hex color such as
#3b82f6, or null.namestring1 to 40 characters
scopestringWhat the tag labels:
postfor posts,changelogfor changelog entries.One ofpostchangelogcreated_atstring · date-timeupdated_atstring · date-time
Example
{
"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"
}