Tags

The workspace tag library the dashboard's pickers offer: list it (with the tags in use on contacts and AI agents), add to it, rename and delete.

Every route takes Authorization: Bearer <ACCESS_TOKEN> unless the auth line says otherwise. Ids are numbers. Errors use the shape on the errors page.

Route	Scope	What it does
`GET /v1/tags`	`contacts.read`	A workspace's tag library, A–Z.
`POST /v1/tags`	`contacts.write`	Add a tag to the library.
`PATCH /v1/tags/{id}`	`contacts.write`	Rename a library tag.
`DELETE /v1/tags/{id}`	`contacts.write`	Remove a tag from the library.

GET https://api.bluereacher.com/v1/tags

Auth: Bearer access token. Scope: contacts.read.

A workspace's tag library, A–Z.

The library is the list the dashboard's tag pickers and Settings › Tags manage. A contact's tags are kept on the contact itself, so a tag can be on contacts without being in the library (imports, platform sync, automations). Pass include_in_use=1 to get those too: rows with source: "contact" (on contacts only) or source: "agent" (an AI agent's tag, with agent_name) and id: null. Only library rows have an id and can be renamed or deleted.

Parameters

Name	In	Type	Required	Description
`workspace_id`	query	number	yes	The workspace.
`search`	query	string	no	Part of a name.
`include_in_use`	query	boolean	no	1 = also the tags that are on contacts or AI agents but not in the library.

Request

curl -X GET "https://api.bluereacher.com/v1/tags?workspace_id=7&search=vi" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": [
    {
      "id": 310,
      "workspace_id": 7,
      "name": "vip",
      "source": "library",
      "created_at": "2026-11-04T02:10:00.000Z",
      "updated_at": "2026-11-04T02:10:00.000Z"
    },
    {
      "id": 311,
      "workspace_id": 7,
      "name": "demo-booked",
      "source": "library",
      "created_at": "2026-11-04T02:11:00.000Z",
      "updated_at": "2026-11-04T02:11:00.000Z"
    },
    {
      "id": null,
      "workspace_id": 7,
      "name": "Sales Agent",
      "source": "agent",
      "agent_name": "Sales Agent",
      "created_at": null,
      "updated_at": null
    }
  ]
}

Status	When	Message
200	OK
400	No workspace_id	`workspace_id is required.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): contacts.read. This integration was granted: …`
404	Workspace does not exist or is not owned by the installer (same response for both)	`Workspace not found or not accessible to this token`

Create tag

POST https://api.bluereacher.com/v1/tags

Auth: Bearer access token. Scope: contacts.write.

Add a tag to the library.

Up to 100 characters. Creating a name the workspace already has answers 200 with the existing tag (201 when it is new), so the call is safe to repeat. The library row makes the tag available in pickers; it does not tag any contact — use Add tags on a contact for that.

Parameters

Name	In	Type	Required	Description
`workspace_id`	body	number	yes	The workspace.
`name`	body	string	yes	The tag.

Request

curl -X POST "https://api.bluereacher.com/v1/tags" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "name": "vip"
}'

Responses

A 201 reply (Created):

{
  "success": true,
  "message": "Tag created",
  "data": {
    "id": 310,
    "workspace_id": 7,
    "name": "vip",
    "source": "library",
    "created_at": "2026-11-04T02:10:00.000Z",
    "updated_at": "2026-11-04T02:10:00.000Z"
  }
}

Status	When	Message
201	Created
200	The name was already in the library
400	No name, or over 100 characters	`name is required.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): contacts.write. This integration was granted: …`
404	Workspace does not exist or is not owned by the installer (same response for both)	`Workspace not found or not accessible to this token`

Rename tag

PATCH https://api.bluereacher.com/v1/tags/{id}

Auth: Bearer access token. Scope: contacts.write.

Rename a library tag.

Renames the library row only; contacts that carry the old name keep it. A name another tag in the workspace already has answers 409.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	The tag id (from List tags).
`name`	body	string	yes	The new name.

Request

curl -X PATCH "https://api.bluereacher.com/v1/tags/310" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP client"
}'

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Tag updated",
  "data": {
    "id": 310,
    "workspace_id": 7,
    "name": "VIP client",
    "source": "library",
    "created_at": "2026-11-04T02:10:00.000Z",
    "updated_at": "2026-11-04T03:00:00.000Z"
  }
}

Status	When	Message
200	OK
400	No name	`name is required.`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): contacts.write. This integration was granted: …`
404	Tag does not exist or is not owned by the installer (same response for both)	`Tag not found or not accessible to this token`
409	Another tag has that name	`A tag with this name already exists in the workspace.`

Delete tag

DELETE https://api.bluereacher.com/v1/tags/{id}

Auth: Bearer access token. Scope: contacts.write.

Remove a tag from the library.

The library row only: contacts that carry the tag keep it (remove it from them with Remove tags). AI agent tags are not library rows and cannot be deleted here.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	The tag id.

Request

curl -X DELETE "https://api.bluereacher.com/v1/tags/310" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Tag deleted",
  "data": {
    "id": 310,
    "workspace_id": 7,
    "name": "vip"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): contacts.write. This integration was granted: …`
404	Tag does not exist or is not owned by the installer (same response for both)	`Tag not found or not accessible to this token`

On this page