Tags

List workspace tags and manage the tags applied to a thread.

Postman CollectionDownload the ready-made collection with all endpoints pre-configured.

Use with Claude, ChatGPT & moreConnect any AI assistant to BlackTwist via our MCP server. No code required.

Tags let you organize posts and drafts by topic, campaign, or anything else. Each tag belongs to a scope: either a team workspace or your personal workspace. A thread can have any number of tags from its own scope.

List Tags

`GET /api/v1/tags`

Returns all tags available in the workspace, sorted by name.Query Parameters:

teamId (optional) — Team ID. Use personal for the personal workspace, or omit to use the active workspace from your settings.

Request

curl "https://blacktwist.app/api/v1/tags?teamId=personal" \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "tags": [
    {
      "id": "tag_abc123",
      "name": "Marketing",
      "color": "#F97316",
      "teamId": null,
      "createdBy": "user_xyz789",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Get Thread Tags

`GET /api/v1/posts/:threadId/tags`

Returns the tags currently applied to a thread.

Request

curl https://blacktwist.app/api/v1/posts/abc123xyz/tags \
  -H "Authorization: Bearer bt_api_..."

Response

{
  "threadId": "abc123xyz",
  "tags": [
    {
      "id": "tag_abc123",
      "name": "Marketing",
      "color": "#F97316"
    }
  ]
}

Set Thread Tags

`PUT /api/v1/posts/:threadId/tags`

Replaces the thread's tags with the exact set of names you pass in — this is not additive. Tag names that don't exist yet in the thread's scope are created automatically (a color is assigned for you). Names are matched case-insensitively and duplicates are ignored. Pass an empty array to remove all tags from the thread.Request Body:

tagNames (required) — Array of tag names. The full desired set for the thread.

Request

curl -X PUT https://blacktwist.app/api/v1/posts/abc123xyz/tags \
  -H "Authorization: Bearer bt_api_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tagNames": ["Marketing", "Newsletter"]
  }'

Response

{
  "threadId": "abc123xyz",
  "tags": [
    {
      "id": "tag_abc123",
      "name": "Marketing",
      "color": "#F97316"
    },
    {
      "id": "tag_def456",
      "name": "Newsletter",
      "color": "#3B82F6"
    }
  ]
}

Follow-ups

Other