On this page
POST/tags
POST /tags
X-API-Key: sk_live_...
Content-Type: application/json
Idempotency-Key: optional-uuid
Credits: 0
Rate limit: 30 / minute (shared control bucket)
Idempotency: Idempotency-Key → POST:/tags
Request
{ "label": "VIP", "description": "High-priority prospect — schedule a call.", "color": "teal" }
All three fields required. Description 20–280 characters. Colors: gray|teal|pink|indigo|lime|orange. Max 20 active customs; max 40 docs (including archived).
Response 201
Same shape as a custom row from GET /tags. Unarchive-via-create (same name as an archived tag) also returns 201.
Errors
| Code | When |
|---|---|
validation_error | Bad label / description / color |
conflict | Duplicate active name, or custom-tag limits reached |
MCP
Tool: create_tag — optional idempotencyKey.