Operation
Define a tag
POST
/tag-definitionsDefine a tag: its slug, label, kind, what it applies to and who may grant it. A slug in use (archived or not) is 409 TAG_SLUG_TAKEN. Needs tags.write over every account, and adding `api` to grantableBy needs a person rather than a key (403 TAG_API_GRANTING_NEEDS_STAFF).
Headers
Idempotency-KeystringOptional- Makes the write safe to retry. The first request with a key does the work and its response is stored for 24 hours; a repeat with the same key and the same request (method, path, query, X-Ticketlayer-Channel, TL-Version and body) gets that stored status and body back, marked `Idempotent-Replay: true`, without running again. The key is scoped to your organisation and your credential. The same key with a different request is 422 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running waits for it, then answers 409 IDEMPOTENT_REQUEST_IN_PROGRESS if it has not finished. Only a 2xx is stored: after an error the key is free again. Omit the header and the request behaves as it always has.
Body
Returns
Tag defined
Errors
- 400
- Bad Request - Invalid input
- 401
- Unauthorized - Authentication required
- 403
- Forbidden - Insufficient permissions
- 404
- Not Found - Resource not found
- 409
- The slug is already defined in this organisation
- 500
- Internal Server Error
Every error names its code and links to it. All error codes
curl -X POST "https://api.ticketlayer.com/v1/tag-definitions" \ -H "Authorization: Bearer tlak_..." \ -H "X-Ticketlayer-Org: your-org-slug" \ -H "Content-Type: application/json" \ -d '{ "slug": "member", "label": "Members", "description": "Current club members, renewed each season", "kind": "customer", "appliesTo": [ "customers" ], "grantableBy": [ "staff" ] }'Response 201
{
"tagDefinition": {
"id": "tgd_abc123",
"slug": "member",
"label": "Members",
"description": "Current club members",
"kind": "customer",
"appliesTo": [
"customers"
],
"grantableBy": [
"staff",
"code"
],
"autoDefined": false,
"archivedAt": null,
"createdAt": "2026-09-24T10:00:00.000Z",
"updatedAt": "2026-09-24T10:00:00.000Z"
}
}