Tag APIs
Overview
Manage workspace tags and bulk tag updates.
Tag properties
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The tag ID. |
tag | string | The tag value. |
type | TagType | The tag type, it can be 'common', 'client', 'message', 'conversation', 'clientStage' or 'convStage'. |
order | number | The tag order. |
description | string | The tag description. |
createdAt | DateTime | The created timestamp. |
Tags API
Get tags.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
tag | string | Tag filter. |
type | TagType | Tag type filter. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery tags($input: TagsInput!) {
tags(input: $input) {
nodes {
id
tag
type
createdAt
}
}
}
input TagsInput {
workspaceId: Int! # Workspace ID.
tag: String # Tag filter.
type: TagType # Tag type filter.
}The query above returns JSON structured like this:
{
"data": {
"tags": {
"nodes": [
{
"id": "tag_123",
"tag": "vip",
"type": "client",
"createdAt": "2026-03-16T00:00:00.000Z"
}
]
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"tags","variables":{"input":{"workspaceId":12,"tag":"vip","type":"client"}},"query":"query tags($input: TagsInput!) {\n tags(input: $input) {\n nodes {\n id\n tag\n type\n createdAt\n }\n }\n}"}'Create Tag API
Create a tag.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
type | TagType! | Required. Tag type. |
tag | string | Required. Tag value. |
order | number | Tag order. |
description | string | Tag description. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation createTag($input: TagCreateInput!) {
createTag(input: $input) {
id
tag
type
createdAt
}
}
input TagCreateInput {
workspaceId: Int! # Workspace ID.
type: TagType! # Tag type.
tag: String! # Tag value.
order: Int # Tag order.
description: String # Tag description.
}The mutation above returns JSON structured like this:
{
"data": {
"createTag": {
"id": "tag_123",
"tag": "vip",
"type": "client",
"createdAt": "2026-03-16T00:00:00.000Z"
}
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"createTag","variables":{"input":{"workspaceId":12,"type":"client","tag":"vip","order":1,"description":"High-value customers"}},"query":"mutation createTag($input: TagCreateInput!) {\n createTag(input: $input) {\n id\n tag\n type\n createdAt\n }\n}"}'Bulk Patch Tags API
Bulk patch tags.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
patches | json | Required. List of tag patch items, it's explained in the next section. |
patches fields
| Attribute | Type | Description |
|---|---|---|
id | string | Required. The ID of the tag to patch. |
order | number | Optional. The new order of the tag. |
description | string | Optional. The new description of the tag. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation bulkPatchTags($input: TagBulkPatchInput!) {
bulkPatchTags(input: $input)
}
input TagBulkPatchInput {
workspaceId: Int! # Workspace ID.
patches: [TagBulkPatchItemInput!]! # List of tag patch items.
}The mutation above returns JSON structured like this:
{
"data": {
"bulkPatchTags": true
}
}Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"bulkPatchTags","variables":{"input":{"workspaceId":12,"patches":[{"id":"tag_123","order":1,"description":"High-value customers"},{"id":"tag_124","order":2}]}},"query":"mutation bulkPatchTags($input: TagBulkPatchInput!) {\n bulkPatchTags(input: $input)\n}"}'Delete Tag API
Delete a tag from the workspace’s tag list. The tag is removed permanently and cannot be restored.
Access: MANAGE_WORKSPACE (Owner, Admin). Works with workspace API keys. Agent API keys are rejected.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The ID of the tag to delete. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation deleteTag($input: TagDeleteInput!) {
deleteTag(input: $input) {
id
tag
type
createdAt
}
}
input TagDeleteInput {
workspaceId: Int! # Workspace ID.
id: ID! # Tag ID.
}The mutation above returns JSON structured like this:
{
"data": {
"deleteTag": {
"id": "tag_123",
"tag": "vip",
"type": "client",
"createdAt": "2026-08-21T11:05:00.000Z"
}
}
}Clients, conversations, and messages store their tags by name, so deleting a tag does not remove it from records that already carry it. Those records keep the name in tags until you remove it with untagClient, untagConv, or untagMessage. Tagging a record with the same name again re-creates the tag automatically.
An ID that does not exist in the workspace, or a tag that was already deleted, returns an error.
Programming language examples
cURL
curl -X POST 'https://gateway.bcrumbs.net/core/gq' \
-H 'authorization: API-KEY' \
-H 'content-type: application/json' \
-d '{"operationName":"deleteTag","variables":{"input":{"workspaceId":12,"id":"tag_123"}},"query":"mutation deleteTag($input: TagDeleteInput!) {\n deleteTag(input: $input) {\n id\n tag\n type\n createdAt\n }\n}"}'