openapi: 3.1.0 info: title: ClickUp Lists API description: >- The ClickUp Lists API enables developers to manage Lists, which are containers that hold tasks within a Space or Folder. Lists define the workflow statuses available to tasks and serve as the primary grouping mechanism for related work items. The API supports creating, updating, and deleting Lists, as well as retrieving List details and the tasks they contain. version: '2.0' contact: name: ClickUp Support url: https://help.clickup.com termsOfService: https://clickup.com/terms externalDocs: description: ClickUp Lists API Documentation url: https://developer.clickup.com/reference/get-lists servers: - url: https://api.clickup.com/api/v2 description: ClickUp API v2 Production Server tags: - name: Lists description: >- Operations for managing Lists within ClickUp Spaces and Folders. security: - bearerAuth: [] paths: /folder/{folder_id}/list: get: operationId: getLists summary: Get lists in a folder description: >- Retrieves all Lists within a specified Folder. Optionally includes archived Lists in the response. tags: - Lists parameters: - $ref: '#/components/parameters/folderId' - name: archived in: query description: >- Include archived Lists in the response. schema: type: boolean default: false responses: '200': description: Successfully retrieved lists content: application/json: schema: type: object properties: lists: type: array items: $ref: '#/components/schemas/List' '401': description: Unauthorized '404': description: Folder not found post: operationId: createList summary: Create a list in a folder description: >- Creates a new List within a specified Folder. The List can be configured with a name, content description, due date, priority, assignee, and status. tags: - Lists parameters: - $ref: '#/components/parameters/folderId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateListRequest' responses: '200': description: List created successfully content: application/json: schema: $ref: '#/components/schemas/List' '400': description: Bad request '401': description: Unauthorized '404': description: Folder not found /space/{space_id}/list: get: operationId: getFolderlessLists summary: Get folderless lists description: >- Retrieves all Lists that are directly within a Space and not inside any Folder. These are sometimes called folderless Lists. tags: - Lists parameters: - $ref: '#/components/parameters/spaceId' - name: archived in: query description: >- Include archived Lists in the response. schema: type: boolean default: false responses: '200': description: Successfully retrieved folderless lists content: application/json: schema: type: object properties: lists: type: array items: $ref: '#/components/schemas/List' '401': description: Unauthorized '404': description: Space not found post: operationId: createFolderlessList summary: Create a folderless list description: >- Creates a new List directly within a Space, without placing it inside a Folder. tags: - Lists parameters: - $ref: '#/components/parameters/spaceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateListRequest' responses: '200': description: List created successfully content: application/json: schema: $ref: '#/components/schemas/List' '400': description: Bad request '401': description: Unauthorized '404': description: Space not found /list/{list_id}: get: operationId: getList summary: Get a list description: >- Retrieves details of a specific List, including its statuses, content, and configuration. tags: - Lists parameters: - $ref: '#/components/parameters/listId' responses: '200': description: Successfully retrieved list content: application/json: schema: $ref: '#/components/schemas/List' '401': description: Unauthorized '404': description: List not found put: operationId: updateList summary: Update a list description: >- Updates the properties of an existing List, including its name, content, due date, priority, assignee, and status. tags: - Lists parameters: - $ref: '#/components/parameters/listId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateListRequest' responses: '200': description: List updated successfully content: application/json: schema: $ref: '#/components/schemas/List' '400': description: Bad request '401': description: Unauthorized '404': description: List not found delete: operationId: deleteList summary: Delete a list description: >- Permanently deletes a List and all tasks it contains. This action cannot be undone. tags: - Lists parameters: - $ref: '#/components/parameters/listId' responses: '200': description: List deleted successfully '401': description: Unauthorized '404': description: List not found /list/{list_id}/member: get: operationId: getListMembers summary: Get list members description: >- Retrieves the members who have access to a specific List. tags: - Lists parameters: - $ref: '#/components/parameters/listId' responses: '200': description: Successfully retrieved list members content: application/json: schema: type: object properties: members: type: array items: $ref: '#/components/schemas/Member' '401': description: Unauthorized '404': description: List not found components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- ClickUp personal API token or OAuth access token. parameters: folderId: name: folder_id in: path required: true description: >- The unique identifier of the Folder. schema: type: integer spaceId: name: space_id in: path required: true description: >- The unique identifier of the Space. schema: type: integer listId: name: list_id in: path required: true description: >- The unique identifier of the List. schema: type: integer schemas: List: type: object description: >- A List object representing a container for tasks within a Space or Folder. properties: id: type: string description: >- The unique identifier of the List. name: type: string description: >- The name of the List. orderindex: type: integer description: >- The order index of the List. content: type: string nullable: true description: >- The content description of the List. status: type: object nullable: true properties: status: type: string description: >- The status name. color: type: string description: >- The hex color code. hide_label: type: boolean description: >- Whether to hide the status label. description: >- The status of the List. priority: type: object nullable: true properties: priority: type: string description: >- The priority level. color: type: string description: >- The hex color code. description: >- The priority of the List. assignee: type: object nullable: true description: >- The user assigned to the List. task_count: type: integer nullable: true description: >- The number of tasks in the List. due_date: type: string nullable: true description: >- The due date as a Unix timestamp in milliseconds. start_date: type: string nullable: true description: >- The start date as a Unix timestamp in milliseconds. folder: type: object properties: id: type: string description: >- The Folder ID. name: type: string description: >- The Folder name. hidden: type: boolean description: >- Whether the Folder is hidden. access: type: boolean description: >- Whether the user has access. description: >- The Folder this List belongs to. space: type: object properties: id: type: string description: >- The Space ID. name: type: string description: >- The Space name. access: type: boolean description: >- Whether the user has access. description: >- The Space this List belongs to. archived: type: boolean description: >- Whether the List is archived. override_statuses: type: boolean description: >- Whether the List overrides the Space statuses. statuses: type: array items: type: object properties: id: type: string description: >- The status ID. status: type: string description: >- The status name. orderindex: type: integer description: >- The order index. color: type: string description: >- The hex color code. type: type: string description: >- The status type. description: >- Available statuses for the List. permission_level: type: string description: >- The permission level of the List. CreateListRequest: type: object required: - name description: >- Request body for creating a new List. properties: name: type: string description: >- The name of the List. content: type: string description: >- The content description of the List. due_date: type: integer format: int64 description: >- Due date as Unix timestamp in milliseconds. due_date_time: type: boolean description: >- Whether the due date includes a time component. priority: type: integer minimum: 1 maximum: 4 description: >- Priority level. 1 is Urgent, 2 is High, 3 is Normal, 4 is Low. assignee: type: integer description: >- User ID to assign to the List. status: type: string description: >- The status to set on the List. UpdateListRequest: type: object description: >- Request body for updating an existing List. properties: name: type: string description: >- The updated name of the List. content: type: string description: >- The updated content description. due_date: type: integer format: int64 description: >- Updated due date as Unix timestamp in milliseconds. due_date_time: type: boolean description: >- Whether the due date includes a time component. priority: type: integer minimum: 1 maximum: 4 description: >- Updated priority level. assignee: type: integer nullable: true description: >- User ID to assign, or null to unassign. unset_status: type: boolean description: >- Set to true to clear the List status. Member: type: object description: >- A member with access to a List. properties: id: type: integer description: >- The user ID. username: type: string description: >- The username. email: type: string format: email description: >- The email address. color: type: string description: >- The user color. profilePicture: type: string format: uri nullable: true description: >- URL of the profile picture. initials: type: string description: >- The user initials.