openapi: 3.2.0
info:
  title: ClickUp API v2 Reference Task Checklists API
  description: The ClickUp API enables you to programmatically access and manage your ClickUp resources.
  contact: {}
  version: '2.0'
servers:
- url: https://api.clickup.com/api
  description: ClickUp
  variables: {}
security:
- Authorization_Token: []
tags:
- name: Task Checklists
paths:
  /v2/task/{task_id}/checklist:
    parameters: []
    post:
      summary: Create Checklist
      tags:
      - Task Checklists
      description: Add a new checklist to a task.
      operationId: CreateChecklist
      parameters:
      - name: task_id
        in: path
        description: ''
        required: true
        style: simple
        schema:
          type: string
          examples:
          - 9hz
      - name: custom_task_ids
        in: query
        description: If you want to reference a task by it's custom task id, this value must be `true`.
        style: form
        explode: true
        schema:
          type: boolean
          examples:
          - true
      - name: team_id
        in: query
        description: "When the `custom_task_ids` parameter is set to `true`, the Workspace ID must be provided using the `team_id` parameter.\n \\\nFor example: `custom_task_ids=true&team_id=123`."
        style: form
        explode: true
        schema:
          type: number
          contentEncoding: double
          examples:
          - 123
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              title: CreateChecklistrequest
              required:
              - name
              type: object
              properties:
                name:
                  type: string
              examples:
              - name: Checklist
            example:
              name: Checklist
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                title: CreateChecklistresponse
                required:
                - checklist
                type: object
                properties:
                  checklist:
                    title: Checklist
                    required:
                    - id
                    - task_id
                    - name
                    - orderindex
                    - resolved
                    - unresolved
                    - items
                    type: object
                    properties:
                      id:
                        type: string
                      task_id:
                        type: string
                      name:
                        type: string
                      orderindex:
                        type: integer
                        contentEncoding: int32
                      resolved:
                        type: integer
                        contentEncoding: int32
                      unresolved:
                        type: integer
                        contentEncoding: int32
                      items:
                        type: array
                        items:
                          type: string
                        description: ''
                    examples:
                    - id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                      task_id: 9hz
                      name: Checklist
                      orderindex: 0
                      resolved: 0
                      unresolved: 0
                      items: []
                examples:
                - checklist:
                    id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                    task_id: 9hz
                    name: Checklist
                    orderindex: 0
                    resolved: 0
                    unresolved: 0
                    items: []
              example:
                checklist:
                  id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                  task_id: 9hz
                  name: Checklist
                  orderindex: 0
                  resolved: 0
                  unresolved: 0
                  items: []
      deprecated: false
  /v2/checklist/{checklist_id}:
    parameters: []
    put:
      summary: Edit Checklist
      tags:
      - Task Checklists
      description: Rename a task checklist, or reorder a checklist so it appears above or below other checklists on a task.
      operationId: EditChecklist
      parameters:
      - name: checklist_id
        in: path
        description: b8a8-48d8-a0c6-b4200788a683 (uuid)
        required: true
        style: simple
        schema:
          type: string
          examples:
          - b955c4dc
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              title: EditChecklistrequest
              type: object
              properties:
                name:
                  type: string
                position:
                  description: "Position refers to the order of appearance of checklists on a task.\\\n \\\nTo set a checklist to appear at the top of the checklists section of a task, use `\"position\": 0`."
                  type: integer
                  contentEncoding: int32
              examples:
              - name: Updated Checklist
                position: 1
            example:
              name: Updated Checklist
              position: 1
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                contentMediaType: application/json
      deprecated: false
    delete:
      summary: Delete Checklist
      tags:
      - Task Checklists
      description: Delete a checklist from a task.
      operationId: DeleteChecklist
      parameters:
      - name: checklist_id
        in: path
        description: b8a8-48d8-a0c6-b4200788a683 (uuid)
        required: true
        style: simple
        schema:
          type: string
          examples:
          - b955c4dc
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                examples:
                - {}
                contentMediaType: application/json
              example: {}
      deprecated: false
  /v2/checklist/{checklist_id}/checklist_item:
    parameters: []
    post:
      summary: Create Checklist Item
      tags:
      - Task Checklists
      description: Add a line item to a task checklist.
      operationId: CreateChecklistItem
      parameters:
      - name: checklist_id
        in: path
        description: b8a8-48d8-a0c6-b4200788a683 (uuid)
        required: true
        style: simple
        schema:
          type: string
          examples:
          - b955c4dc
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              title: CreateChecklistItemrequest
              type: object
              properties:
                name:
                  type: string
                assignee:
                  type: integer
                  contentEncoding: int32
              examples:
              - name: Checklist Item
                assignee: 183
            example:
              name: Checklist Item
              assignee: 183
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                title: CreateChecklistItemresponse
                required:
                - checklist
                type: object
                properties:
                  checklist:
                    title: Checklist1
                    required:
                    - id
                    - task_id
                    - name
                    - date_created
                    - orderindex
                    - resolved
                    - unresolved
                    - items
                    type: object
                    properties:
                      id:
                        type: string
                      task_id:
                        type: string
                      name:
                        type: string
                      date_created:
                        type: string
                      orderindex:
                        type: integer
                        contentEncoding: int32
                      resolved:
                        type: integer
                        contentEncoding: int32
                      unresolved:
                        type: integer
                        contentEncoding: int32
                      items:
                        type: array
                        items:
                          title: Item
                          required:
                          - id
                          - name
                          - orderindex
                          - assignee
                          - resolved
                          - parent
                          - date_created
                          - children
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            orderindex:
                              type: integer
                              contentEncoding: int32
                            assignee:
                              $ref: '#/paths/~1v2~1task~1{task_id}~1comment/get/responses/200/content/application~1json/schema/properties/comments/items/properties/assignee'
                            resolved:
                              type: boolean
                            parent:
                              type:
                              - string
                              - 'null'
                            date_created:
                              type: string
                            children:
                              type: array
                              items:
                                type: string
                              description: ''
                          examples:
                          - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                            name: Checklist Item
                            orderindex: 0
                            assignee:
                              id: 183
                              username: John Doe
                              email: example@email.com
                              color: '#827718'
                              initials: JD
                              profilePicture: https://attachments.clickup.com/profilePictures/183_nx1.jpg
                            resolved: false
                            parent: null
                            date_created: '1567711566859'
                            children: []
                        description: ''
                    examples:
                    - id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                      task_id: 9hv
                      name: Checklist
                      date_created: '1567711563204'
                      orderindex: 0
                      resolved: 0
                      unresolved: 1
                      items:
                      - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                        name: Checklist Item
                        orderindex: 0
                        assignee:
                          id: 183
                          username: John Doe
                          email: example@email.com
                          color: '#827718'
                          initials: JD
                          profilePicture: https://attachments.clickup.com/profilePictures/183_nx1.jpg
                        resolved: false
                        parent: null
                        date_created: '1567711566859'
                        children: []
                examples:
                - checklist:
                    id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                    task_id: 9hv
                    name: Checklist
                    date_created: '1567711563204'
                    orderindex: 0
                    resolved: 0
                    unresolved: 1
                    items:
                    - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                      name: Checklist Item
                      orderindex: 0
                      assignee:
                        id: 183
                        username: John Doe
                        email: example@email.com
                        color: '#827718'
                        initials: JD
                        profilePicture: https://attachments.clickup.com/profilePictures/183_nx1.jpg
                      resolved: false
                      parent: null
                      date_created: '1567711566859'
                      children: []
              example:
                checklist:
                  id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                  task_id: 9hv
                  name: Checklist
                  date_created: '1567711563204'
                  orderindex: 0
                  resolved: 0
                  unresolved: 1
                  items:
                  - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                    name: Checklist Item
                    orderindex: 0
                    assignee:
                      id: 183
                      username: John Doe
                      email: example@email.com
                      color: '#827718'
                      initials: JD
                      profilePicture: https://attachments.clickup.com/profilePictures/183_nx1.jpg
                    resolved: false
                    parent: null
                    date_created: '1567711566859'
                    children: []
      deprecated: false
  /v2/checklist/{checklist_id}/checklist_item/{checklist_item_id}:
    parameters: []
    put:
      summary: Edit Checklist Item
      tags:
      - Task Checklists
      description: 'Update an individual line item in a task checklist. \

        \

        You can rename it, set the assignee, mark it as resolved, or nest it under another checklist item.'
      operationId: EditChecklistItem
      parameters:
      - name: checklist_id
        in: path
        description: b8a8-48d8-a0c6-b4200788a683 (uuid)
        required: true
        style: simple
        schema:
          type: string
          examples:
          - b955c4dc
      - name: checklist_item_id
        in: path
        description: e491-47f5-9fd8-d1dc4cedcc6f (uuid)
        required: true
        style: simple
        schema:
          type: string
          examples:
          - 21e08dc8
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              title: EditChecklistItemrequest
              type: object
              properties:
                name:
                  type: string
                assignee:
                  type:
                  - string
                  - 'null'
                resolved:
                  type: boolean
                parent:
                  description: To nest a checklist item under another checklist item, include the other item's `checklist_item_id`.
                  type:
                  - string
                  - 'null'
              examples:
              - name: Updated Checklist Item
                assignee: null
                resolved: true
                parent: null
            example:
              name: Updated Checklist Item
              assignee: null
              resolved: true
              parent: null
        required: true
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                title: EditChecklistItemresponse
                required:
                - checklist
                type: object
                properties:
                  checklist:
                    title: Checklist2
                    required:
                    - id
                    - task_id
                    - name
                    - date_created
                    - orderindex
                    - resolved
                    - unresolved
                    - items
                    type: object
                    properties:
                      id:
                        type: string
                      task_id:
                        type: string
                      name:
                        type: string
                      date_created:
                        type: string
                      orderindex:
                        type: integer
                        contentEncoding: int32
                      resolved:
                        type: integer
                        contentEncoding: int32
                      unresolved:
                        type: integer
                        contentEncoding: int32
                      items:
                        type: array
                        items:
                          title: Item1
                          required:
                          - id
                          - name
                          - orderindex
                          - assignee
                          - resolved
                          - parent
                          - date_created
                          - children
                          type: object
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            orderindex:
                              type: integer
                              contentEncoding: int32
                            assignee:
                              type:
                              - string
                              - 'null'
                            resolved:
                              type: boolean
                            parent:
                              type:
                              - string
                              - 'null'
                            date_created:
                              type: string
                            children:
                              type: array
                              items:
                                type: string
                              description: ''
                          examples:
                          - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                            name: Updated Checklist Item
                            orderindex: 0
                            assignee: null
                            resolved: true
                            parent: null
                            date_created: '1567711566859'
                            children: []
                        description: ''
                    examples:
                    - id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                      task_id: 9hv
                      name: Checklist
                      date_created: '1567711563204'
                      orderindex: 0
                      resolved: 1
                      unresolved: 0
                      items:
                      - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                        name: Updated Checklist Item
                        orderindex: 0
                        assignee: null
                        resolved: true
                        parent: null
                        date_created: '1567711566859'
                        children: []
                examples:
                - checklist:
                    id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                    task_id: 9hv
                    name: Checklist
                    date_created: '1567711563204'
                    orderindex: 0
                    resolved: 1
                    unresolved: 0
                    items:
                    - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                      name: Updated Checklist Item
                      orderindex: 0
                      assignee: null
                      resolved: true
                      parent: null
                      date_created: '1567711566859'
                      children: []
              example:
                checklist:
                  id: b955c4dc-b8a8-48d8-a0c6-b4200788a683
                  task_id: 9hv
                  name: Checklist
                  date_created: '1567711563204'
                  orderindex: 0
                  resolved: 1
                  unresolved: 0
                  items:
                  - id: 21e08dc8-e491-47f5-9fd8-d1dc4cedcc6f
                    name: Updated Checklist Item
                    orderindex: 0
                    assignee: null
                    resolved: true
                    parent: null
                    date_created: '1567711566859'
                    children: []
      deprecated: false
    delete:
      summary: Delete Checklist Item
      tags:
      - Task Checklists
      description: Delete a line item from a task checklist.
      operationId: DeleteChecklistItem
      parameters:
      - name: checklist_id
        in: path
        description: b8a8-48d8-a0c6-b4200788a683 (uuid)
        required: true
        style: simple
        schema:
          type: string
          examples:
          - b955c4dc
      - name: checklist_item_id
        in: path
        description: e491-47f5-9fd8-d1dc4cedcc6f (uuid)
        required: true
        style: simple
        schema:
          type: string
          examples:
          - 21e08dc8
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                type: object
                examples:
                - {}
                contentMediaType: application/json
              example: {}
      deprecated: false
components:
  securitySchemes:
    Authorization_Token:
      name: Authorization
      type: apiKey
      in: header
      description: 'API token required for authentication. Two types of tokens are supported:

        **Personal API Key** Obtain from ClickUp''s settings page under ''Apps'' and add it to the header as `Authorization: pk_...`

        **OAuth2 Access Token** Generated through the OAuth2 flow and add it to the header as `Authorization: Bearer {access_token}`'