> ## Documentation Index > Fetch the complete documentation index at: https://docs.gable.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a tag definition. > Create a tag definition. Always creates a USER tag: SYSTEM tags are seeded by Gable and cannot be created through the API. The id is minted by the server as a slug of the name, so the caller influences neither the id nor the kind. ## OpenAPI ````yaml /api-reference/bundled.yaml post /v0/tags openapi: 3.1.0 info: title: Gable API description: > API to interact with the Gable platform ## Authorization All API requests require an API key to be passed in the `X-API-KEY` header. For instructions on finding your API key and api endpoint check out the [API Key documentation](../docs/api-keys.md). Example: `curl -H "X-API-KEY: " https://api-{organization}.gable.ai/v0/ping` contact: name: Gable Engineering url: https://gable.ai email: engineers@gable.ai version: 1.54.0 servers: - url: https://{hostname}.gable.ai description: Gable API variables: hostname: default: demo-api description: Customer environment assigned by Gable security: - ApiKeyAuth: [] tags: - name: action - name: api-keys - name: auth - name: changelog - name: config - name: debug - name: settings - name: slack - name: sso - name: webhook - name: notifications - name: telemetry - name: component - name: components - name: sca - name: cross-service-components - name: lineage - name: events - name: measurements - name: defect-report - name: data-tagging description: Tag vocabulary management and field level tagging of lineage boundaries. paths: /v0/tags: post: tags: - data-tagging summary: Create a tag definition. description: >- Create a tag definition. Always creates a USER tag: SYSTEM tags are seeded by Gable and cannot be created through the API. The id is minted by the server as a slug of the name, so the caller influences neither the id nor the kind. operationId: postTag requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostTagRequest' responses: '201': description: The created definition, carrying the minted id. content: application/json: schema: $ref: '#/components/schemas/TagDefinitionResponse' '400': description: >- Bad Request (missing or empty name, or a name whose slug cannot form a valid id) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The minted id is already taken, including by a SYSTEM tag such as `pii`. Ids are the join key every field tag carries, so a collision is refused rather than reused: sharing one id between two definitions would unlabel fields. Also returned when concurrent vocabulary writes lose the version condition three times, since the whole vocabulary is a single stored item. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PostTagRequest: type: object description: >- Create a tag definition. The server sets three things the caller cannot influence: `kind` is always USER, `status` is always active, and `id` is minted as a slug of `name`. Detection is off on a new tag. properties: name: type: string minLength: 1 description: >- Display name. The id is derived from it, so a name whose slug collides with an existing definition (including a SYSTEM id such as `pii`) is refused with 409, and one that would not form a valid id is refused with 400. description: type: string description: Optional longer explanation of what the tag means. color: type: string description: Optional display color for chips and badges. required: - name additionalProperties: false TagDefinitionResponse: type: object description: A single tag definition, as returned by create and update. properties: tag: $ref: '#/components/schemas/TagDefinition' required: - tag additionalProperties: false ErrorResponse: type: object required: - message properties: id: type: number title: type: string message: type: string TagDefinition: type: object description: >- One tag in the organization's vocabulary. Field tags reference it by `id` and the read joins it in, so a rename takes effect everywhere at once. readOnly properties are not settable on POST or PUT. properties: id: type: string readOnly: true description: >- Minted from `name` (lowercased, runs of non alphanumerics collapsed to `_`). A collision, including with a SYSTEM id such as `pii`, is refused with 409. A later rename changes `name` only. name: type: string minLength: 1 description: Display name, shown on chips and in pickers. kind: $ref: '#/components/schemas/TagKind' readOnly: true description: Set by the server. POST /v0/tags always creates a USER tag. status: $ref: '#/components/schemas/TagStatus' description: type: string description: Optional longer explanation of what the tag means. color: type: string description: Optional display color, also carried on every field tag reference. detection_enabled: type: boolean description: >- Advisory only. The read defaults an unset stored value to false. The ingest detector always applies `pii`, gated on nothing but that definition existing, so the value is inert on every tag. created_at: type: string format: date-time readOnly: true description: Absent on the seeded SYSTEM tags. created_by: readOnly: true description: Null for the seeded SYSTEM tags and for API key writes. anyOf: - type: string - type: 'null' required: - id - name - kind - status - detection_enabled additionalProperties: false TagKind: type: string description: >- Where a tag definition came from. SYSTEM tags are seeded by Gable (`pii`, `phi`, `pifi`, `secret`) and cannot be created or deleted through the API; the UI deactivates them instead. POST /v0/tags only ever mints USER tags. enum: - SYSTEM - USER TagStatus: type: string description: >- Lifecycle state of a tag definition, lowercase on the wire to match the `status` query param of GET /v0/tags and translated by the handler to the uppercase stored form. Deactivation is a status flip, not a delete: an `inactive` definition drops out of the default list and out of pickers, an ADD naming it is refused with `TAG_INACTIVE`, and component reads stop rendering it on every field. The stored assignments survive in the event log and render again on reactivation. Ingest detection is not gated on status: a scan keeps applying `pii` while the definition is inactive, and those assignments surface once it is reactivated. enum: - active - inactive securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.