Tags
BlueSuite MCP tools for tags
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
List the tags defined for one kind of record. Call this before tagging something, to find the tag IDs and to avoid creating a duplicate of a tag that already exists.
| Field | Type / accepted values | Required | Details |
|---|
taggable_type | "request", "quote", "job", "invoice", "contact" | Yes | Which kind of record the tag belongs to. Tags are scoped per type: a "Priority" tag on jobs is a separate tag from a "Priority" tag on contacts, so this is always required. |
page | integer | No | Page number (default: 1) |
per_page | integer | No | Results per page (default: 25) minimum: 1. maximum: 100. |
search | string | No | Search tags by name |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Create a new tag for one kind of record. Check list_tags first, tags are matched by ID, not name, so creating a second "Urgent" tag splits the records between them.
| Field | Type / accepted values | Required | Details |
|---|
name | string | Yes | Tag name, e.g. "Urgent" or "Needs parts". |
taggable_type | "request", "quote", "job", "invoice", "contact" | Yes | Which kind of record the tag belongs to. Tags are scoped per type: a "Priority" tag on jobs is a separate tag from a "Priority" tag on contacts, so this is always required. |
description | string | No | Optional description of what the tag means. |
color | string | No | Hex color such as #3b82f6. Defaults to no color if omitted. |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Rename a tag, change its color, or edit its description. A tag's record type cannot be changed, create a new tag instead.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Tag ID |
name | string | No | New tag name |
description | string | No | New description |
color | string | No | New hex color, e.g. #ef4444 |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Delete a tag. This removes it from every record it is currently applied to.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Tag ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Get the tags currently applied to one record (a job, quote, invoice, request or contact).
| Field | Type / accepted values | Required | Details |
|---|
taggable_type | "request", "quote", "job", "invoice", "contact" | Yes | Which kind of record the tag belongs to. Tags are scoped per type: a "Priority" tag on jobs is a separate tag from a "Priority" tag on contacts, so this is always required. |
taggable_id | integer | Yes | ID of the record. |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Set which tags are applied to one record. This REPLACES the record's tags rather than adding to them, so to add a tag you must first call get_entity_tags and send the existing tag IDs along with the new one. Sending an empty list clears all tags from the record.
| Field | Type / accepted values | Required | Details |
|---|
taggable_type | "request", "quote", "job", "invoice", "contact" | Yes | Which kind of record the tag belongs to. Tags are scoped per type: a "Priority" tag on jobs is a separate tag from a "Priority" tag on contacts, so this is always required. |
taggable_id | integer | Yes | ID of the record to tag. |
tag_ids | array of JSON value | Yes | The complete set of tag IDs the record should end up with. Must belong to the same taggable_type. Use list_tags to resolve names to IDs. |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
The downloadable tool schemas include the full input and output contracts. Tables describe schema-level required fields; cross-field rules still apply.