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

# Create tag

> Creates a custom tag in your organization. Use the returned `id` when assigning tags to a document via **PATCH** `/contents/v1/documents/{content_id}` (pass tag IDs in the `tags` array, not names). Tag names supplied at upload time via **POST** `/contents/v1/documents` are resolved by name; for post-upload changes, use tag IDs from this endpoint or from List tags.



## OpenAPI

````yaml /api-rest/openapi/openapi_content_data.json post /contents/v1/tags
openapi: 3.1.0
info:
  title: Bigdata Content API
  description: API for managing and accessing private content documents uploaded by users.
  version: 1.0.0
servers:
  - url: https://api.bigdata.com/
security:
  - ApiKeyAuth: []
paths:
  /contents/v1/tags:
    post:
      tags:
        - Tags
      summary: Create tag
      description: >-
        Creates a custom tag in your organization. Use the returned `id` when
        assigning tags to a document via **PATCH**
        `/contents/v1/documents/{content_id}` (pass tag IDs in the `tags` array,
        not names). Tag names supplied at upload time via **POST**
        `/contents/v1/documents` are resolved by name; for post-upload changes,
        use tag IDs from this endpoint or from List tags.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTagPayload'
            example:
              tag_name: testing tag 2
      responses:
        '200':
          description: >-
            The created tag, including its `id` for use when updating document
            metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagDetails'
              example:
                id: 019e3a99-6952-7dd4-adf5-b0b341959e11
                name: testing tag 2
                created_at: '2026-05-18T10:19:53.044285Z'
                updated_at: '2026-05-18T10:19:53.044290Z'
                file_count: 0
        '400':
          description: Invalid request body (e.g. missing or empty tag_name).
        '401':
          description: Unauthorized - Invalid or missing API key.
components:
  schemas:
    CreateTagPayload:
      type: object
      description: Request body for creating a custom tag.
      required:
        - tag_name
      properties:
        tag_name:
          type: string
          description: Display name for the new tag.
          example: testing tag 2
    TagDetails:
      type: object
      description: Detailed information about a tag.
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the tag.
          example: 019a48b4-e573-7203-945a-2e7c4c164217
        name:
          type: string
          description: >-
            Name of the tag (e.g. `from:user@email.com`, `to:user@email.com`,
            `broker:Broker Name` or a custom one provided by the user).
          example: from:user@email.com
        created_at:
          type: string
          format: date-time
          description: Timestamp when the tag was created.
          example: '2025-11-03T07:53:26.150858Z'
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the tag was last updated.
          example: '2025-11-03T07:53:26.150859Z'
        file_count:
          type: integer
          description: Number of files associated with this tag.
          example: 40
      required:
        - id
        - name
        - created_at
        - updated_at
        - file_count
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your API key. Include it in every request as the X-API-KEY header.
        Create and manage keys in the Developer Platform.

````