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

# Add tag options to a category field

> Ensures option names exist on an existing plain tag field. Existing options are preserved, repeated names are idempotent, and only genuinely new names are appended. This endpoint does not edit stage fields.



## OpenAPI

````yaml /openapi/customer-api.json post /project/{projectId}/data-model/{id}/fields/{fieldKey}/tag-options
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Flow customer API reference. Start with the [quickstart](/api/quickstart)
    and [authentication guide](/api/authentication).
  title: Customer API
  version: 1.0.0
servers:
  - description: Flow API
    url: https://backend.branch.flowengineering.com
security: []
tags:
  - name: Automations
  - name: Branches
  - name: Comments
  - name: Convert
  - name: Data Model
  - name: Diagrams
  - name: Entities
  - name: Files
  - name: Import
  - name: Notifications
  - name: Projects
  - name: ReqIF
  - name: ReqIF Import
  - name: Shared Access Grants
  - name: User Groups
  - name: Users
paths:
  /project/{projectId}/data-model/{id}/fields/{fieldKey}/tag-options:
    post:
      tags:
        - Data Model
      summary: Add tag options to a category field
      description: >-
        Ensures option names exist on an existing plain tag field. Existing
        options are preserved, repeated names are idempotent, and only genuinely
        new names are appended. This endpoint does not edit stage fields.
      operationId: CustomerCategoriesController_addTagOptions
      parameters:
        - in: path
          name: projectId
          required: true
          schema:
            type: string
        - in: path
          name: id
          required: true
          schema:
            type: string
        - in: path
          name: fieldKey
          required: true
          schema:
            type: string
        - description: Workspace identifier
          in: header
          name: customer
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            examples:
              addOptions:
                summary: Append missing tag options
                value:
                  tags:
                    - name: Medium
                    - name: Urgent
            schema:
              $ref: '#/components/schemas/CustomerAddTagOptionsDto'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerCategoryResponseDto'
          description: ''
      security:
        - api-key: []
        - bearer: []
components:
  schemas:
    CustomerAddTagOptionsDto:
      properties:
        tags:
          description: >-
            Option names to ensure on an existing plain tag field. Existing
            names are treated idempotently; only new names append new tag
            options, and omitted options are preserved.
          example:
            - name: Medium
            - name: Urgent
          items:
            $ref: '#/components/schemas/CustomerTagInputDto'
          type: array
      required:
        - tags
      type: object
    CustomerCategoryResponseDto:
      properties:
        builtin:
          type: boolean
        categoryType:
          enum:
            - folder
            - item
          type: string
        fields:
          items:
            $ref: '#/components/schemas/CustomerFieldResponseDto'
          type: array
        humanIdPrefix:
          type: string
        humanIdPrefixLocked:
          type: boolean
        id:
          type: string
        name:
          type: string
      required:
        - id
        - name
        - categoryType
        - builtin
        - fields
        - humanIdPrefix
        - humanIdPrefixLocked
      type: object
    CustomerTagInputDto:
      properties:
        name:
          description: >-
            Display name of the tag option. Customer API writes refer to plain
            tag options by name; Flow stores and preserves the internal option
            id.
          example: Medium
          type: string
      required:
        - name
      type: object
    CustomerFieldResponseDto:
      properties:
        key:
          type: string
        multi:
          type: boolean
        name:
          type: string
        tags:
          items:
            $ref: '#/components/schemas/CustomerTagResponseDto'
          type: array
        type:
          type: string
      required:
        - key
        - name
        - type
      type: object
    CustomerTagResponseDto:
      properties:
        id:
          type: string
        name:
          type: string
      required:
        - name
      type: object
  securitySchemes:
    api-key:
      in: header
      name: X-API-Key
      type: apiKey
    bearer:
      bearerFormat: JWT
      scheme: bearer
      type: http

````