> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a contact tag

> Create a contact tag, or get the existing one: names are unique per pool ignoring case, so creating "evento 1" when "Evento 1" exists returns that tag (200, `created: false`) instead of a twin (201, `created: true`). Creating a tag does not apply it; use `POST /v1/contacts/tags/add`. Requires contact and company tags on the workspace: without them every tag endpoint answers 400 with `details.code` `ENTITY_TAGS_NOT_ENABLED`; tell the user instead of retrying.

    > **Required scope:** `CONTACTS_WRITE`
    >
    > **Rate limit:** 30 requests per minute



## OpenAPI

````yaml https://openapi.enginy.ai/definitions.json post /v1/contacts/tags
openapi: 3.1.0
info:
  title: Enginy API
  version: 1.0.0
  description: Public API for Enginy platform
servers:
  - url: https://openapi.enginy.ai
    description: Configured server
security: []
tags:
  - name: AI Variables
    description: >-
      Manage AI variables and discover the entity fields you can reference in
      prompts and entity requests.
  - name: Inbox
    description: >-
      Inbox endpoints for listing contact threads, reading thread messages,
      managing tags, and sending manual replies.
  - name: Workflows
    description: >-
      Build, validate, publish, run, and inspect advanced (graph) workflows,
      plus the block/condition catalog needed to author a workflow plan.
paths:
  /v1/contacts/tags:
    post:
      tags:
        - Contacts
      summary: Create a contact tag
      description: >-
        Create a contact tag, or get the existing one: names are unique per pool
        ignoring case, so creating "evento 1" when "Evento 1" exists returns
        that tag (200, `created: false`) instead of a twin (201, `created:
        true`). Creating a tag does not apply it; use `POST
        /v1/contacts/tags/add`. Requires contact and company tags on the
        workspace: without them every tag endpoint answers 400 with
        `details.code` `ENTITY_TAGS_NOT_ENABLED`; tell the user instead of
        retrying.

            > **Required scope:** `CONTACTS_WRITE`
            >
            > **Rate limit:** 30 requests per minute
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >-
                    Tag name, 1 to 20 characters after trimming. Names are
                    unique per pool, ignoring case. When a tag with this name
                    already exists, it is returned instead.
                color:
                  type: string
                  description: >-
                    Tag colour as a `#rrggbb` hex value. The Enginy app offers
                    `#767676` (gray), `#E99342` (orange), `#E367BC` (pink),
                    `#6F78F0` (purple), `#F24473` (red), `#5BBE7E` (green),
                    `#57A4E9` (blue) and `#5EB2CC` (cyan).
              required:
                - name
                - color
            example:
              name: Evento 1
              color: '#57A4E9'
      responses:
        '200':
          description: >-
            A tag with this name already existed; it is returned with `created:
            false`
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      tag:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: Tag ID
                          name:
                            type: string
                            description: Tag name
                          color:
                            type: string
                            description: Tag colour as a `#rrggbb` hex value
                        required:
                          - id
                          - name
                          - color
                      created:
                        type: boolean
                        description: >-
                          True when the tag was created (201); false when an
                          existing tag of that name was returned (200).
                    required:
                      - tag
                      - created
                required:
                  - status
                  - message
                  - data
        '201':
          description: 'The tag was created (`created: true`)'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - success
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      tag:
                        type: object
                        properties:
                          id:
                            type: integer
                            description: Tag ID
                          name:
                            type: string
                            description: Tag name
                          color:
                            type: string
                            description: Tag colour as a `#rrggbb` hex value
                        required:
                          - id
                          - name
                          - color
                      created:
                        type: boolean
                        description: >-
                          True when the tag was created (201); false when an
                          existing tag of that name was returned (200).
                    required:
                      - tag
                      - created
                required:
                  - status
                  - message
                  - data
        '400':
          description: >-
            Tags are not enabled for this workspace (`details.code`
            `ENTITY_TAGS_NOT_ENABLED`), or a tag rule was broken (`details.code`
            `ENTITY_TAG_INVALID`, `details.reason` one of `nameEmpty`,
            `nameTooLong`, `colorInvalid`, `emptyUpdate`, `tooManyEntityIds`,
            `tooManyTagIds`).
      security:
        - apiKey: []
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.