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

# Create Project Data Definition Tag

> Create a data definition tag in the project.

> [!WARNING]
>
> **Closed Beta**\\
>
> Available to a limited set of invited customers. Contact your account team to join.
> The request and response contract may change before general availability (GA).

#### Permissions

The permissions required to access this endpoint. See [Permissions Reference](https://docs.mixpanel.com/reference/permissions.md) for what each role grants.**Required Permissions: **write\_data\_definitions**Granted By Role: **Owner Admin


## OpenAPI

````yaml /openapi/platform.openapi.json post /v1/projects/{project_id}/data-definition-tags
openapi: 3.1.0
info:
  title: Mixpanel Platform API
  version: '1'
  description: ''
servers:
  - url: https://platform-us.mixpanel.com
    description: US
  - url: https://platform-eu.mixpanel.com
    description: EU
  - url: https://platform-in.mixpanel.com
    description: IN
security: []
paths:
  /v1/projects/{project_id}/data-definition-tags:
    post:
      tags:
        - Projects
        - Data Definitions
      summary: Create Project Data Definition Tag
      description: Create a data definition tag in the project.
      operationId: create_project_data_definition_tag
      parameters:
        - $ref: '#/components/parameters/ProjectIdPathParameter'
        - $ref: '#/components/parameters/MixpanelVersionHeader'
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDataDefinitionTagRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataDefinitionTagResponse'
        '422':
          $ref: '#/components/responses/RequestValidationError'
        default:
          $ref: '#/components/responses/Error'
      security:
        - ServiceAccountAuth: []
components:
  parameters:
    ProjectIdPathParameter:
      in: path
      name: project_id
      schema:
        title: Project ID
        type: string
      required: true
      description: The unique identifier for the project.
    MixpanelVersionHeader:
      in: header
      name: Mixpanel-Version
      required: false
      description: >-
        Optional date-based API version pin.


        If omitted, the request is served by the **latest** API version, and the
        caller accepts that a future release may introduce a breaking change to
        the response contract. If set to a supported version date, that
        version's contract is honored and will not receive a breaking change.
      schema:
        default: '2026-08-13'
        type: string
        title: Mixpanel-Version
    IdempotencyKeyHeader:
      in: header
      name: Idempotency-Key
      required: false
      description: >-
        Optional, client-provided key guaranteeing the operation is idempotent
        on success: if a request is replayed, the response includes
        `Idempotent-Replayed: true`.


        Reusing a key with a different request body, or while a request with the
        same key is still in flight, returns a `409`.


        Use a unique, random value for each request (a UUID v4 works well).
      schema:
        type: string
        maxLength: 255
        title: Idempotency-Key
  schemas:
    CreateDataDefinitionTagRequest:
      additionalProperties: false
      properties:
        name:
          description: The tag's name. Unique within the project.
          maxLength: 175
          minLength: 1
          title: Name
          type: string
      required:
        - name
      title: CreateDataDefinitionTagRequest
      type: object
    DataDefinitionTagResponse:
      properties:
        id:
          description: The tag's ID.
          title: Id
          type: string
        name:
          description: The tag's name.
          title: Name
          type: string
        entity_count:
          description: The number of definitions carrying the tag.
          title: Entity Count
          type: integer
      required:
        - id
        - name
        - entity_count
      title: DataDefinitionTagResponse
      type: object
    RequestValidationErrorResponse:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: A stable reference that identifies the problem type, if applicable.
          title: Type
        status:
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          title: Status
          type: integer
        instance:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            A stable reference that identifies the specific occurrence of the
            problem, if applicable.
          title: Instance
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem, if applicable.
          title: Detail
        error_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Opaque identifier for this error occurrence. Include it when
            contacting support so the corresponding server-side error can be
            located.
          title: Error Id
        errors:
          anyOf:
            - items:
                $ref: '#/components/schemas/RequestValidationErrorItem'
              type: array
            - type: 'null'
          default: null
          description: The set of request validation errors.
          title: Errors
        title:
          description: A short, human-readable summary of the problem type.
          readOnly: true
          title: Title
          type: string
      required:
        - status
        - title
      title: RequestValidationErrorResponse
      type: object
    ErrorResponse:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: A stable reference that identifies the problem type, if applicable.
          title: Type
        status:
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          title: Status
          type: integer
        instance:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            A stable reference that identifies the specific occurrence of the
            problem, if applicable.
          title: Instance
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem, if applicable.
          title: Detail
        error_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Opaque identifier for this error occurrence. Include it when
            contacting support so the corresponding server-side error can be
            located.
          title: Error Id
        title:
          description: A short, human-readable summary of the problem type.
          readOnly: true
          title: Title
          type: string
      required:
        - status
        - title
      title: ErrorResponse
      type: object
    RequestValidationErrorItem:
      properties:
        type:
          description: Machine-readable validation error type, e.g. 'missing'.
          title: Type
          type: string
        loc:
          description: Location of the offending value in the request.
          items:
            anyOf:
              - type: string
              - type: integer
          title: Loc
          type: array
        msg:
          description: Human-readable description of the error.
          title: Msg
          type: string
        ctx:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: Additional context about the error, if any.
          title: Ctx
      required:
        - type
        - loc
        - msg
      title: RequestValidationErrorItem
      type: object
  responses:
    RequestValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RequestValidationErrorResponse'
    Error:
      description: Error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ServiceAccountAuth:
      type: http
      description: >-
        This endpoint uses [Service
        Account](https://docs.mixpanel.com/reference/service-accounts#authenticating-with-a-service-account)
        authentication.
      scheme: basic

````