API Reference

The reference below covers every endpoint in the Tags API. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.

GET/api/v1/tags

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/tags"

{  "tags": [    {      "id": "cmq5tag00alk34567890",      "name": "VIP",      "color": "amber",      "createdAt": "2026-09-27T14:02:00.000Z",      "counts": {        "contacts": 42,        "leads": 3,        "companies": 5,        "deals": 7      }    }  ]}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:tags."}

{  "error": "Rate limit exceeded."}

POST/api/v1/tags

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 40

color?|

Lengthlength <= 20

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/tags" \  -H "Content-Type: application/json" \  -d '{    "name": "VIP",    "color": "amber"  }'

{  "tag": {    "id": "string",    "name": "string",    "color": "string",    "createdAt": "2019-08-24T14:15:22Z",    "counts": {      "contacts": 0,      "leads": 0,      "companies": 0,      "deals": 0    }  },  "created": true}

{  "tag": {    "id": "cmq5tag00alk34567890",    "name": "VIP",    "color": "amber",    "createdAt": "2026-09-27T14:02:00.000Z",    "counts": {      "contacts": 0,      "leads": 0,      "companies": 0,      "deals": 0    }  },  "created": true}

{  "error": "name is required."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:tags."}

{  "error": "Rate limit exceeded."}

PATCH/api/v1/tags/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The tag's ID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name?string

Length1 <= length <= 40

color?|

Lengthlength <= 20

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/tags/string" \  -H "Content-Type: application/json" \  -d '{    "name": "Key account"  }'

{  "tag": {    "id": "string",    "name": "string",    "color": "string",    "createdAt": "2019-08-24T14:15:22Z",    "counts": {      "contacts": 0,      "leads": 0,      "companies": 0,      "deals": 0    }  }}

{  "error": "Send name, color, or both."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:tags."}

{  "error": "Tag not found."}

{  "error": "A tag named \"Key account\" already exists."}

{  "error": "Rate limit exceeded."}

DELETE/api/v1/tags/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The tag's ID.

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/tags/string"

{  "deleted": 1,  "id": "string"}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:tags."}

{  "error": "Tag not found."}

{  "error": "Rate limit exceeded."}

POST/api/v1/tags/assign

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

entity*string

The record type. Case-insensitive.

Value in

"CONTACT"
"LEAD"
"COMPANY"
"DEAL"

recordIds*array<string>

Items1 <= items <= 500

tagIds*array<string>

Items1 <= items <= 50

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/tags/assign" \  -H "Content-Type: application/json" \  -d '{    "entity": "CONTACT",    "recordIds": [      "cmq2cont0alk34567891",      "cmq2cont1alk34567892"    ],    "tagIds": [      "cmq5tag00alk34567890"    ]  }'

{  "entity": "CONTACT",  "recordIds": [    "cmq2cont0alk34567891",    "cmq2cont1alk34567892"  ],  "tagIds": [    "cmq5tag00alk34567890"  ],  "updated": 2}

{  "error": "entity must be one of: CONTACT, LEAD, COMPANY, DEAL."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:tags."}

{  "error": "No contact with id cmq2cont9alk34567899 in this workspace. Nothing was changed."}

{  "error": "Rate limit exceeded."}

POST/api/v1/tags/unassign

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

entity*string

The record type. Case-insensitive.

Value in

"CONTACT"
"LEAD"
"COMPANY"
"DEAL"

recordIds*array<string>

Items1 <= items <= 500

tagIds*array<string>

Items1 <= items <= 50

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/tags/unassign" \  -H "Content-Type: application/json" \  -d '{    "entity": "CONTACT",    "recordIds": [      "cmq2cont0alk34567891",      "cmq2cont1alk34567892"    ],    "tagIds": [      "cmq5tag00alk34567890"    ]  }'

{  "entity": "CONTACT",  "recordIds": [    "cmq2cont0alk34567891",    "cmq2cont1alk34567892"  ],  "tagIds": [    "cmq5tag00alk34567890"  ],  "updated": 2}

{  "error": "recordIds must contain at least one id."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:tags."}

{  "error": "No contact with id cmq2cont9alk34567899 in this workspace. Nothing was changed."}

{  "error": "Rate limit exceeded."}

API Reference

200application/json

401application/json

403application/json

429application/json

200application/json

201application/json

400application/json

401application/json

403application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

429application/json

200application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`