clickup Custom Fields API

openapi: 3.1.0
info:
  title: ClickUp Comments Authorization Custom Fields API
  description: The ClickUp Comments API provides endpoints for creating and retrieving comments on tasks, views, and lists. Comments support rich text formatting, mentions, and attachments. Developers can use this API to build integrations that synchronize discussions between ClickUp and other collaboration tools, or to programmatically add status updates and notes to tasks.
  version: '2.0'
  contact:
    name: ClickUp Support
    url: https://help.clickup.com
  termsOfService: https://clickup.com/terms
servers:
- url: https://api.clickup.com/api/v2
  description: ClickUp API v2 Production Server
security:
- bearerAuth: []
tags:
- name: Custom Fields
  description: Operations for retrieving custom field definitions and setting custom field values on tasks.
paths:
  /list/{list_id}/field:
    get:
      operationId: getAccessibleCustomFields
      summary: Get accessible custom fields
      description: Retrieves all custom fields that are accessible on a specific list. Returns field definitions including type, name, configuration, and possible values for dropdown and label fields.
      tags:
      - Custom Fields
      parameters:
      - $ref: '#/components/parameters/listId'
      responses:
        '200':
          description: Successfully retrieved custom fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  fields:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomFieldDefinition'
        '401':
          description: Unauthorized
        '404':
          description: List not found
  /task/{task_id}/field/{field_id}:
    post:
      operationId: setCustomFieldValue
      summary: Set custom field value
      description: Sets the value of a custom field on a task. The value format depends on the custom field type. For dropdown fields, provide the option order index. For label fields, provide an array of label IDs. For relationship fields, provide an array of task IDs.
      tags:
      - Custom Fields
      parameters:
      - $ref: '#/components/parameters/taskId'
      - $ref: '#/components/parameters/fieldId'
      - name: custom_task_ids
        in: query
        description: If you want to reference a task by its custom task ID, this value must be true.
        schema:
          type: boolean
      - name: team_id
        in: query
        description: Required when custom_task_ids is set to true. The Workspace ID.
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  description: The value to set for the custom field. The type depends on the field type. Strings for text, numbers for numeric, arrays for labels and relationships, integers for dropdowns.
              required:
              - value
      responses:
        '200':
          description: Custom field value set successfully
        '400':
          description: Bad request - invalid value for field type
        '401':
          description: Unauthorized
        '404':
          description: Task or field not found
    delete:
      operationId: removeCustomFieldValue
      summary: Remove custom field value
      description: Removes the value of a custom field from a task, resetting it to empty.
      tags:
      - Custom Fields
      parameters:
      - $ref: '#/components/parameters/taskId'
      - $ref: '#/components/parameters/fieldId'
      - name: custom_task_ids
        in: query
        description: If you want to reference a task by its custom task ID, this value must be true.
        schema:
          type: boolean
      - name: team_id
        in: query
        description: Required when custom_task_ids is set to true. The Workspace ID.
        schema:
          type: integer
      responses:
        '200':
          description: Custom field value removed successfully
        '401':
          description: Unauthorized
        '404':
          description: Task or field not found
components:
  parameters:
    taskId:
      name: task_id
      in: path
      required: true
      description: The unique identifier of the task.
      schema:
        type: string
    fieldId:
      name: field_id
      in: path
      required: true
      description: The unique identifier of the custom field.
      schema:
        type: string
    listId:
      name: list_id
      in: path
      required: true
      description: The unique identifier of the list.
      schema:
        type: integer
  schemas:
    CustomFieldDefinition:
      type: object
      description: A custom field definition with its configuration and type information.
      properties:
        id:
          type: string
          description: The unique identifier of the custom field.
        name:
          type: string
          description: The name of the custom field.
        type:
          type: string
          enum:
          - url
          - drop_down
          - email
          - phone
          - date
          - text
          - checkbox
          - number
          - currency
          - tasks
          - users
          - emoji
          - label
          - automatic_progress
          - manual_progress
          - short_text
          - location
          description: The type of the custom field.
        type_config:
          type: object
          description: Configuration specific to the field type. Contains options for dropdown and label fields, currency settings, etc.
          properties:
            default:
              type: integer
              description: Default option index for dropdown fields.
            placeholder:
              type: string
              nullable: true
              description: Placeholder text for text fields.
            new_drop_down:
              type: boolean
              description: Whether this is a new-style dropdown.
            options:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: The option ID.
                  name:
                    type: string
                    description: The option display name.
                  value:
                    type: string
                    nullable: true
                    description: The option value.
                  type:
                    type: string
                    nullable: true
                    description: The option type.
                  color:
                    type: string
                    nullable: true
                    description: The hex color code of the option.
                  orderindex:
                    type: integer
                    description: The order index of the option.
                  label:
                    type: string
                    nullable: true
                    description: The label text for the option.
              description: Available options for dropdown and label fields.
            include_guests:
              type: boolean
              description: Whether to include guests for user fields.
            include_team_members:
              type: boolean
              description: Whether to include team members for user fields.
            precision:
              type: integer
              description: Decimal precision for number and currency fields.
            currency_type:
              type: string
              description: Currency type code for currency fields (e.g., USD, EUR).
        date_created:
          type: string
          description: Unix timestamp when the field was created.
        hide_from_guests:
          type: boolean
          description: Whether the field is hidden from guests.
        required:
          type: boolean
          description: Whether the field is required on tasks.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: ClickUp personal API token or OAuth access token.
externalDocs:
  description: ClickUp Comments API Documentation
  url: https://developer.clickup.com/reference/get-task-comments