--- updatedAt: 2026-07-01T21:22:52.000Z agentTools: projectIndex: https://developer.clickup.com/llms.txt --- # Create Task Create a new task.\ \ Custom Field values in the request body are only saved when the field is applicable to the task's `custom_item_id`. Use [Get Custom Fields](ref:getaccessiblecustomfields) and each field's `applied_objects` to determine applicability before creating the task. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "ClickUp API v2 Reference", "description": "The ClickUp API enables you to programmatically access and manage your ClickUp resources.\n\n## Authentication\nThe API supports two authentication methods:\n- **Personal API Token**: Use for testing and personal integrations. Add token to requests with header: `Authorization: pk_...`\n- **OAuth 2.0**: Required for building apps for other users. Uses authorization code flow.\n\n## Getting Started\nOur [Getting Started Guide](https://developer.clickup.com/docs/index) provides a comprehensive overview of how to use the ClickUp API.\n\n## Custom Fields by Task Type\nCustom Fields can be scoped to specific custom task types. Use the Custom Fields endpoints to read each field's `applied_objects` array (`object_type` `19` = custom task type). Task responses only include applicable Custom Fields, and write operations reject or ignore values for non-applicable fields.\n", "contact": {}, "version": "2.0" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "servers": [ { "url": "https://api.clickup.com/api", "description": "ClickUp", "variables": {} } ], "paths": { "/v2/list/{list_id}/task": { "post": { "summary": "Create Task", "tags": [ "Tasks" ], "description": "Create a new task.\\\n \\\nCustom Field values in the request body are only saved when the field is applicable to the task's `custom_item_id`. Use [Get Custom Fields](https://developer.clickup.com/reference/getaccessiblecustomfields) and each field's `applied_objects` to determine applicability before creating the task.", "operationId": "CreateTask", "parameters": [ { "name": "list_id", "in": "path", "description": "", "required": true, "style": "simple", "schema": { "type": "number", "contentEncoding": "double", "examples": [ 123 ] } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "title": "CreateTaskrequest", "required": [ "name" ], "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "assignees": { "type": "array", "items": { "type": "integer", "contentEncoding": "int32" }, "description": "" }, "archived": { "type": "boolean" }, "group_assignees": { "type": "array", "items": { "type": "string" }, "description": "Assign multiple user groups to the task." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "" }, "status": { "type": "string" }, "priority": { "type": [ "integer", "null" ], "contentEncoding": "int32" }, "due_date": { "type": "integer", "contentEncoding": "int64" }, "due_date_time": { "type": "boolean" }, "time_estimate": { "type": "integer", "contentEncoding": "int32" }, "start_date": { "type": "integer", "contentEncoding": "int64" }, "start_date_time": { "type": "boolean" }, "points": { "type": "number", "description": "Add Sprint Points to the task." }, "notify_all": { "type": "boolean", "description": "If `notify_all` is true, the creator of the task will also be notified. Other assignees and watchers are always notified regardless of this setting." }, "parent": { "description": "You can create a subtask by including an existing task ID.\\\n \\\nThe `parent` task ID you include can be a subtask, but must be in the same List specified in the path parameter.", "type": [ "string", "null" ] }, "markdown_content": { "type": "string", "description": "Markdown formatted description for the task. If both `markdown_content` and `description` are provided, `markdown_content` will be used instead of `description`." }, "links_to": { "description": "Include a task ID to create a linked dependency with your new task.", "type": [ "string", "null" ] }, "check_required_custom_fields": { "description": "When creating a task via API any required Custom Fields are ignored by default (`false`).\\\n \\\nYou can enforce required Custom Fields by including `check_required_custom_fields: true`.", "type": "boolean" }, "custom_fields": { "type": "array", "items": { "title": "SetCustomFieldValueOnCreateTaskrequest", "anyOf": [ { "type": "object", "title": "URL Custom Field", "description": "The `value` must be a string with a valid URL.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "string", "null" ], "example": "https://clickup.com/api" } } }, { "type": "object", "title": "Dropdown Custom Field", "description": "Enter the universal unique identifier (UUID) of the dropdown menu option you want to set. You can find the UUIDs available for each Dropdown Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields) New Dropdown Custom Field options cannot be created from this request.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "string", "null" ], "example": "uuid1234" } } }, { "type": "object", "title": "Email Custom Field", "description": "The `value` must be a string with a valid email address.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "string", "null" ], "example": "user@company.com" } } }, { "type": "object", "title": "Phone Custom Field", "description": "The `value` must be a string with a valid country code.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "string", "null" ], "example": "+1 123 456 7890" } } }, { "type": "object", "title": "Date Custom Field", "description": "The `value` must be Unix time in milliseconds. To display the time in a Date Custom Field in ClickUp, you must include `time: true` in the `value_options` property.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "integer", "null" ], "format": "int64", "example": 1667367645000 }, "value_options": { "type": "object", "properties": { "time": { "type": "boolean", "example": true } } } } }, { "type": "object", "title": "Short or Long Text Custom Field", "description": "Enter a string of text.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "string", "null" ], "example": "This is short or long text in a Custom Field." } } }, { "type": "object", "title": "Number Custom Field", "description": "Enter a number.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "number", "null" ], "example": -28 } } }, { "type": "object", "title": "Money Custom Field", "description": "You can set an amount, but not the currency of a Money Custom Field via the API. You can check the currency of a Money Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields)", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "number", "null" ], "example": 8000 } } }, { "type": "object", "title": "Task Relationship Custom Field", "description": "Enter an array of task ids in the `add` property to add them to a Task Relationship Custom Field. Enter them into the `rem` property to remove tasks from the Relationship. Task Relationship Custom Fields are nullable: `\"value\": null`.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": "object", "properties": { "add": { "type": "array", "items": { "type": "string" } }, "rem": { "type": "array", "items": { "type": "string" } } } } } }, { "type": "object", "title": "People Custom Field", "description": "Enter an array of user ids or a Team id in the `add` property to add them to a People Custom Field. Enter them into the `rem` property to remove users from a People Custom Field. You can get a list of people in the Workspace using [Get Authorized Teams (Workspaces).](https://developer.clickup.com/reference/getauthorizedteams) People Custom Fields are nullable: `\"value\": null`.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": "object", "properties": { "add": { "type": "array", "items": { "type": "number" } }, "rem": { "type": "array", "items": { "type": "number" } } } } } }, { "type": "object", "title": "Emoji (Rating) Custom Field", "description": "Enter an integer that is greater than or equal to zero and where the `count` property is greater than or equal to the `value`. You can find the `count` property for each Emoji (Rating) Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields)", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "integer", "null" ], "format": "int32", "example": 4 } } }, { "type": "object", "title": "Manual Progress Custom Field", "description": "Enter a number between the `start` and `end` values of each Manual Progress Custom Field. For example, for a field with `start: 10` and `end: 30`, sending `current: 20` will be displayed as 50% complete in ClickUp. You can find the `start` and `end` values for each Manual Progress Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields) Manual Progress Custom Fields are nullable: `\"value\": null`.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": "object", "required": [ "current" ], "properties": { "current": { "type": "number", "example": 20 } } } } }, { "type": "object", "title": "Label Custom Field", "description": "Enter an array of the universal unique identifiers (UUIDs) of the labels you want to apply. You can find the UUIDs available for each Label Custom Field using [Get Accessible Custom Fields.](https://developer.clickup.com/reference/getaccessiblecustomfields) Label Custom Fields are nullable: `\"value\": null`.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": "array", "items": { "type": "string", "example": [ "uuid1234", "uuid9876" ] } } } }, { "type": "object", "title": "Location Custom Field", "description": "Include the latitude, longitude, and formatted address as defined in the [Google Maps Geocoding API.](https://developers.google.com/maps/documentation/geocoding/overview)", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": "object", "properties": { "location": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "formatted_address": { "type": "string" } } } } }, { "type": "object", "title": "Button Custom Field", "description": "Set a button Custom Field to `true` to \"click\" it. This will trigger the button's action as if it was clicked in the UI.", "required": [ "id", "value" ], "properties": { "id": { "type": "string" }, "value": { "type": [ "boolean", "null" ], "example": true } } } ] }, "description": "You can include one or more Custom Fields to set them when creating a new task.\\\n \\\nCustom Fields that use object and array type values are nullable by sending `\"value\": null`.\\\n \\\nOnly Custom Fields applicable to the task's `custom_item_id` are saved. Values for fields scoped to other custom task types are ignored. Use a [Get Custom Fields](https://developer.clickup.com/reference/getaccessiblecustomfields) endpoint and check each field's `applied_objects` to see which fields apply to which task types before creating the task." }, "custom_item_id": { "type": "number", "description": "The custom task type ID for this task. A value of `0` (default) creates a standard task type \"Task\".\\\n \\\nThis determines which Custom Fields from the `custom_fields` array are accepted.\\\n \\\nTo get a list of available custom task type IDs for your Workspace, use the [Get Custom Task Types endpoint](https://developer.clickup.com/reference/getcustomitems)." } }, "examples": [ { "name": "New Task Name", "description": "New Task Description", "assignees": [ 183 ], "archived": false, "group_assignees": [ "dd01f92f-48ca-446d-88a1-0beb0e8f5f14" ], "tags": [ "tag name 1" ], "status": "Open", "priority": 3, "due_date": 1508369194377, "due_date_time": false, "time_estimate": 8640000, "start_date": 1567780450202, "start_date_time": false, "points": 3, "notify_all": true, "parent": null, "links_to": null, "check_required_custom_fields": true, "custom_fields": [ { "id": "0a52c486-5f05-403b-b4fd-c512ff05131c", "value": 23 }, { "id": "03efda77-c7a0-42d3-8afd-fd546353c2f5", "value": "Text field input" } ] } ] }, "example": { "name": "New Task Name", "description": "New Task Description", "markdown_description": "New Task Description", "assignees": [ 183 ], "archived": false, "group_assignees": [ "dd01f92f-48ca-446d-88a1-0beb0e8f5f14" ], "email_assignees": [ "dd01f92f-48ca-446d-88a1-0beb0e8f5f13" ], "tags": [ "tag name 1" ], "status": "Open", "priority": 3, "due_date": 1508369194377, "due_date_time": false, "time_estimate": 8640000, "start_date": 1567780450202, "start_date_time": false, "points": 3, "notify_all": true, "parent": null, "links_to": null, "check_required_custom_fields": true, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "value": "Fix critical auth issues" } ] } } }, "required": true }, "responses": { "200": { "description": "", "headers": {}, "content": { "application/json": { "schema": { "title": "CreateTaskresponse.yaml", "type": "object", "example": { "id": "9hx", "custom_id": null, "custom_item_id": 0, "name": "New Task Name", "text_content": "New Task Content", "description": "New Task Content", "markdown_description": "New Task Content", "status": { "id": "p7002367_HxJmgqni", "status": "to do", "color": "#f8ae00", "orderindex": 0, "type": "open" }, "orderindex": "1.00000000000000000000000000000000", "date_created": "1567780450202", "date_updated": "1567780450202", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "assignees": [], "group_assignees": [], "watchers": [], "checklists": [], "tags": [], "parent": null, "top_level_parent": null, "priority": { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" }, "due_date": "1508369194377", "start_date": null, "points": 3, "time_estimate": "8640000", "time_spent": 0, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Fix critical auth issues", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "required": false } ], "dependencies": [], "linked_tasks": [], "locations": [], "team_id": "7002367", "url": "https://app.clickup.com/t/9hx", "sharing": { "public": false, "public_share_expires_on": null, "public_fields": [ "assignees", "priority", "due_date", "content", "comments", "attachments", "customFields", "subtasks", "tags", "checklists", "coverimage" ], "token": null, "seo_optimized": false }, "permission_level": "create", "list": { "id": "15505202", "name": "Sprint Backlog", "access": true }, "project": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "folder": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "space": { "id": "7002367" } }, "properties": { "id": { "type": "string" }, "custom_id": { "type": [ "string", "null" ] }, "custom_item_id": { "type": [ "number", "null" ], "description": "The custom task type ID for this task. A value of `0` (default) creates a standard task type \"Task\".\\\n \\\nTo get a list of available custom task type IDs for your Workspace, use the [Get Custom Task Types endpoint](https://developer.clickup.com/reference/getcustomitems)." }, "name": { "type": "string" }, "text_content": { "type": "string" }, "description": { "type": "string" }, "markdown_description": { "type": "string" }, "status": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/status" }, "orderindex": { "type": "string" }, "date_created": { "type": "string" }, "date_updated": { "type": "string" }, "date_closed": { "type": [ "string", "null" ] }, "date_done": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "creator": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/creator" }, "assignees": { "type": "array", "items": { "type": "string" }, "description": "" }, "group_assignees": { "type": "array", "items": { "type": "string" }, "description": "" }, "watchers": { "type": "array", "items": { "type": "string" }, "description": "" }, "checklists": { "type": "array", "items": { "type": "string" }, "description": "" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "" }, "parent": { "type": [ "string", "null" ] }, "top_level_parent": { "type": [ "string", "null" ] }, "priority": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/priority" }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "points": { "type": [ "number", "null" ] }, "time_estimate": { "type": [ "string", "null" ] }, "time_spent": { "type": "number" }, "custom_fields": { "type": "array", "items": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/custom_fields/items" }, "description": "" }, "dependencies": { "type": "array", "items": { "type": "string" }, "description": "" }, "linked_tasks": { "type": "array", "items": { "type": "string" }, "description": "" }, "locations": { "type": "array", "items": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/locations/items" }, "description": "Array of Lists where the task has been added." }, "team_id": { "type": "string" }, "url": { "type": "string" }, "sharing": { "type": "object", "properties": { "public": { "type": "boolean" }, "public_share_expires_on": { "type": [ "string", "null" ] }, "public_fields": { "type": "array", "items": { "type": "string" } }, "token": { "type": [ "string", "null" ] }, "seo_optimized": { "type": "boolean" } } }, "permission_level": { "type": "string" }, "list": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/list" }, "project": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/folder" }, "folder": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/folder" }, "space": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/space" } } }, "example": { "id": "9hx", "custom_id": null, "custom_item_id": 0, "name": "New Task Name", "text_content": "New Task Content", "description": "New Task Content", "markdown_description": "New Task Content", "status": { "id": "p7002367_HxJmgqni", "status": "to do", "color": "#f8ae00", "orderindex": 0, "type": "open" }, "orderindex": "1.00000000000000000000000000000000", "date_created": "1567780450202", "date_updated": "1567780450202", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "assignees": [], "group_assignees": [], "watchers": [], "checklists": [], "tags": [], "parent": null, "top_level_parent": null, "priority": { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" }, "due_date": "1508369194377", "start_date": null, "points": 3, "time_estimate": "8640000", "time_spent": 0, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Fix critical auth issues", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "required": false } ], "dependencies": [], "linked_tasks": [], "locations": [], "team_id": "7002367", "url": "https://app.clickup.com/t/9hx", "sharing": { "public": false, "public_share_expires_on": null, "public_fields": [ "assignees", "priority", "due_date", "content", "comments", "attachments", "customFields", "subtasks", "tags", "checklists", "coverimage" ], "token": null, "seo_optimized": false }, "permission_level": "create", "list": { "id": "15505202", "name": "Sprint Backlog", "access": true }, "project": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "folder": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "space": { "id": "7002367" } } } } } }, "deprecated": false }, "parameters": [] }, "/v2/task/{task_id}": { "get": { "summary": "Get Task", "tags": [ "Tasks" ], "description": "View information about a task. You can only view task information of tasks you can access. \\\n \\\nTasks with attachments will return an \"attachments\" response. \\\n \\\nDocs attached to a task are not returned.\\\n \\\nThe `custom_fields` array only includes Custom Fields applicable to the task's `custom_item_id`. Use [Get Custom Fields](https://developer.clickup.com/reference/getaccessiblecustomfields) and each field's `applied_objects` to discover which fields apply to which task types.", "operationId": "GetTask", "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 its 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 ] } }, { "name": "include_subtasks", "in": "query", "description": "Include subtasks, default false", "style": "form", "explode": true, "schema": { "type": "boolean" } }, { "name": "include_markdown_description", "in": "query", "description": "To return task descriptions in Markdown format, use `?include_markdown_description=true`.", "style": "form", "explode": true, "schema": { "type": "boolean", "examples": [ true ] } }, { "name": "custom_fields", "in": "query", "description": "Include tasks with specific values in one or more Custom Fields. Custom Relationships are included.\\\n \\\nFor example: `?custom_fields=[{\"field_id\":\"abcdefghi12345678\",\"operator\":\"=\",\"value\":\"1234\"},{\"field_id\":\"jklmnop123456\",\"operator\":\"<\",\"value\":\"5\"}]`\\\n \\\nOnly set Custom Field values display in the `value` property of the `custom_fields` parameter. If you want to include tasks with specific values in only one Custom Field, use `custom_field` instead.\\\n \\\nLearn more about [filtering using Custom Fields.](https://developer.clickup.com/docs/filtertasks)", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "", "headers": {}, "content": { "application/json": { "schema": { "title": "GetTaskresponse", "type": "object", "example": { "id": "9hx", "custom_id": null, "custom_item_id": 0, "name": "Fix login bug", "text_content": "Users are unable to log in when SSO is enabled.", "description": "Users are unable to log in when SSO is enabled.", "status": { "id": "p7001234_FxGmgrnk", "status": "in progress", "color": "#d3d3d3", "orderindex": 1, "type": "custom" }, "orderindex": "1.00000000000000000000000000000000", "date_created": "1567780450202", "date_updated": "1567780450202", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#827718", "email": "user@company.com", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "assignees": [ { "id": 2772463, "username": "Alex Johnson", "color": "#FC575E", "initials": "AJ", "email": "user@company.com", "profilePicture": null } ], "group_assignees": [], "watchers": [ { "id": 2772463, "username": "Alex Johnson", "color": "#FC575E", "initials": "AJ", "email": "user@company.com", "profilePicture": null } ], "checklists": [], "tags": [ { "name": "bug", "tag_fg": "#EA80FC", "tag_bg": "#EA80FC", "creator": 183 } ], "parent": null, "top_level_parent": null, "priority": { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" }, "due_date": "1508369194377", "start_date": null, "points": 3, "time_estimate": "8640000", "time_spent": 0, "custom_fields": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Fix critical auth issues", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "value": "8", "value_richtext": "", "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "value": [ { "id": 2772463, "username": "Alex Johnson", "email": "user@company.com", "color": "#FC575E", "initials": "AJ", "profilePicture": null } ], "value_richtext": "", "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "value": 2, "value_richtext": "", "required": false } ], "dependencies": [ { "task_id": "9hx", "depends_on": "8gx", "type": 1, "date_created": "1675970762803", "userid": "183", "workspace_id": "1234567", "chain_id": null } ], "linked_tasks": [], "locations": [], "team_id": "1234567", "url": "https://app.clickup.com/t/9hx", "sharing": { "public": false, "public_share_expires_on": null, "public_fields": [ "assignees", "priority", "due_date", "content", "comments", "attachments", "customFields", "subtasks", "tags", "checklists", "coverimage" ], "token": null, "seo_optimized": false }, "permission_level": "create", "list": { "id": "15505202", "name": "Sprint Backlog", "access": true }, "project": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "folder": { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true }, "space": { "id": "7002367" }, "attachments": [ { "id": "62447c77-2086-4cda-b274-f53eccf0547b.txt", "date": 1711570108374, "title": "error-logs.txt", "type": 1, "source": 1, "version": 0, "extension": "txt", "thumbnail_small": null, "thumbnail_medium": null, "thumbnail_large": null, "is_folder": null, "mimetype": "text/plain", "hidden": false, "parent_id": "9hx", "size": 140970, "total_comments": 0, "resolved_comments": 0, "user": { "id": 183, "username": "Alex Johnson", "initials": "AJ", "email": "user@company.com", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" }, "deleted": false, "orientation": null, "url": "https://t123456.p.clickup-attachments.com/t123456/62447c77-2086-4cda-b274-f53eccf0547b/error-logs.txt", "email_data": null, "url_w_query": "https://t123456.p.clickup-attachments.com/t123456/62447c77-2086-4cda-b274-f53eccf0547b/error-logs.txt?view=open", "url_w_host": "https://t123456.p.clickup-attachments.com/t123456/62447c77-2086-4cda-b274-f53eccf0547b/error-logs.txt" } ] }, "properties": { "id": { "type": "string" }, "custom_id": { "type": [ "string", "null" ] }, "custom_item_id": { "type": [ "number", "null" ], "description": "The custom task type ID for this task. A value of `0` represents task type \"Task\".\\\n \\\nTo get a list of available custom task type IDs for your Workspace, use the [Get Custom Task Types endpoint](https://developer.clickup.com/reference/getcustomitems)." }, "name": { "type": "string" }, "text_content": { "type": "string" }, "description": { "type": "string" }, "markdown_description": { "type": "string", "description": "Only returned if `include_markdown_description=true` is passed as a query parameter." }, "status": { "title": "Status", "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "color": { "type": "string" }, "orderindex": { "type": "integer", "contentEncoding": "int32" }, "type": { "type": "string" } }, "examples": [ { "id": "p7001234_FxGmgrnk", "status": "in progress", "color": "#d3d3d3", "orderindex": 1, "type": "custom" } ] }, "orderindex": { "type": "string" }, "date_created": { "type": "string" }, "date_updated": { "type": "string" }, "date_closed": { "type": [ "string", "null" ] }, "date_done": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "creator": { "title": "Creator", "type": "object", "properties": { "id": { "type": "integer", "contentEncoding": "int32" }, "username": { "type": "string" }, "color": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } }, "examples": [ { "id": 183, "username": "Alex Johnson", "color": "#827718", "email": "user@company.com", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" } ] }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "color": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } } }, "description": "" }, "group_assignees": { "type": "array", "items": { "type": "object" }, "description": "" }, "watchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "color": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } } }, "description": "" }, "checklists": { "type": "array", "items": { "type": "object" }, "description": "" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "tag_fg": { "type": "string" }, "tag_bg": { "type": "string" }, "creator": { "type": "integer" } } }, "description": "" }, "parent": { "type": [ "string", "null" ] }, "top_level_parent": { "type": [ "string", "null" ] }, "priority": { "title": "Priority", "type": "object", "nullable": true, "properties": { "color": { "type": "string" }, "id": { "type": "string" }, "orderindex": { "type": "string" }, "priority": { "type": "string" } }, "examples": [ { "color": "#f8ae00", "id": "3", "orderindex": "3", "priority": "normal" } ] }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "points": { "type": [ "number", "null" ] }, "time_estimate": { "type": [ "number", "null" ] }, "time_spent": { "type": [ "number", "null" ] }, "custom_fields": { "type": "array", "items": { "title": "CustomFields8", "type": "object", "examples": [ { "id": "d2ab17e0-41d3-4d28-bdbb-f3f0f2c62f8b", "name": "Sprint Goal", "type": "short_text", "type_config": {}, "date_created": "1621915186877", "hide_from_guests": false, "value": "Improve onboarding flow", "value_richtext": "", "required": false }, { "id": "1f3cc395-3448-4264-bedd-590a3b3fa178", "name": "Story Points", "type": "number", "type_config": {}, "date_created": "1627004071219", "hide_from_guests": false, "value": "8", "value_richtext": "", "required": false }, { "id": "f4d2a20d-6759-4420-b897-222dbe2587d4", "name": "Assigned Reviewer", "type": "users", "type_config": { "include_guests": false, "include_team_members": true, "single_user": false }, "date_created": "1618440378816", "hide_from_guests": false, "value": [ { "id": 2772463, "username": "Alex Johnson", "email": "user@company.com", "color": "#FC575E", "initials": "AJ", "profilePicture": null } ], "value_richtext": "", "required": false }, { "id": "b2e4be70-c4d3-4726-985b-46ac25375b28", "name": "Marketing Requirements", "type": "drop_down", "type_config": { "sorting": "manual", "new_drop_down": true, "options": [ { "id": "f8249998-9c0a-4b1d-a8b7-67a072aca05a", "name": "No Marketing Needed", "color": "#b5bcc2", "orderindex": 0 }, { "id": "97704092-e5aa-4005-a87f-677b764d2e4c", "name": "Internal Announcement", "color": "#02BCD4", "orderindex": 1 }, { "id": "c3d4e5f6-a7b8-4c9d-0e1f-a2b3c4d5e6f7", "name": "Release Notes Only", "color": "#7b68ee", "orderindex": 2 }, { "id": "b32b5b93-1839-431e-b9b0-8c4f9de9a84d", "name": "Social Media Post", "color": "#2ecd6f", "orderindex": 3 }, { "id": "87b3c808-a335-4284-a671-e2f9bce66713", "name": "Blog Post", "color": "#f9ae27", "orderindex": 4 }, { "id": "a1c2d3e4-f5a6-7b8c-9d0e-f1a2b3c4d5e6", "name": "Dedicated Campaign with Press", "color": "#e50000", "orderindex": 5 } ] }, "date_created": "1762838079415", "hide_from_guests": false, "value": 2, "value_richtext": "", "required": false }, { "id": "0aef6ee9-3c54-49e7-aa1a-e981845c773a", "name": "Team", "type": "labels", "type_config": { "sorting": "manual", "options": [ { "id": "2245c581-0fb7-4bba-b5f9-d40e421ab2d2", "label": "Frontend", "color": "#bf55ec", "orderindex": 0 }, { "id": "6992d629-f336-4e3a-87a5-6fd0738d91dd", "label": "Backend", "color": "#04A9F4", "orderindex": 1 } ] }, "date_created": "1614656692549", "hide_from_guests": false, "value": [ "978d9762-34f7-4b6e-8e1b-0ac3216deb39", "cd82b57c-7511-4c9d-a25f-0c8d7db807d4" ], "value_richtext": "", "required": false }, { "id": "be43f58e-989e-4233-9f25-27584f094b74", "name": "Office Location", "type": "location", "type_config": {}, "date_created": "1617765143523", "hide_from_guests": false, "value": { "location": { "lat": 47.306988, "lng": -122.5263212 }, "place_id": "ChIJs79efm1TkFQRJjrP-xr8u0M", "formatted_address": "5400 N Pearl St, Tacoma, WA 98407, USA" }, "value_richtext": "", "required": false } ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "type_config": { "type": "object", "description": "The configuration of the Custom Field. The structure of this object varies depending on the [Custom Field type](ref:docs/customfields)." }, "date_created": { "type": "string" }, "hide_from_guests": { "type": "boolean" }, "value": { "description": "The value of the Custom Field. The structure of this value varies depending on the [Custom Field type](https://developer.clickup.com/docs/customfields)." }, "value_richtext": { "type": "string" }, "value_markdown": { "type": "string" }, "required": { "type": "boolean" } } }, "description": "Custom Fields applicable to the task's `custom_item_id`. Fields scoped to other custom task types are excluded. Fields without a value may still appear with their definition." }, "dependencies": { "type": "array", "items": { "type": "object", "properties": { "task_id": { "type": "string" }, "depends_on": { "type": "string" }, "type": { "type": "integer" }, "date_created": { "type": "string" }, "userid": { "type": "string" }, "workspace_id": { "type": "string" }, "chain_id": { "type": [ "string", "null" ] } } }, "description": "" }, "linked_tasks": { "type": "array", "items": { "type": "object" }, "description": "" }, "locations": { "type": "array", "items": { "title": "ListLocation", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the List where the task has been added." }, "name": { "type": "string", "description": "The name of the List where the task has been added." } }, "examples": [ { "id": "123456789", "name": "Secondary List" } ] }, "description": "Array of Lists where the task has been added." }, "team_id": { "type": "string" }, "url": { "type": "string" }, "sharing": { "type": "object", "properties": { "public": { "type": "boolean" }, "public_share_expires_on": { "type": [ "string", "null" ] }, "public_fields": { "type": "array", "items": { "type": "string" } }, "token": { "type": [ "string", "null" ] }, "seo_optimized": { "type": "boolean" } } }, "permission_level": { "type": "string" }, "list": { "title": "List", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "access": { "type": "boolean" } }, "examples": [ { "id": "15505202", "name": "Sprint Backlog", "access": true } ] }, "project": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/folder" }, "folder": { "title": "Folder", "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hidden": { "type": "boolean" }, "access": { "type": "boolean" } }, "examples": [ { "id": "6992470", "name": "Mobile Squad", "hidden": false, "access": true } ] }, "space": { "title": "Space", "type": "object", "properties": { "id": { "type": "string" } }, "examples": [ { "id": "7002367" } ] }, "subtasks": { "type": "array", "description": "Only returned if `include_subtasks=true` is passed as a query parameter.", "items": { "title": "Subtask", "type": "object", "properties": { "id": { "type": "string" }, "custom_item_id": { "type": [ "number", "null" ] }, "name": { "type": "string" }, "status": { "type": "object", "properties": { "status": { "type": "string" }, "orderindex": { "type": "integer" }, "color": { "type": "string" }, "type": { "type": "string" } } }, "orderindex": { "type": "string" }, "date_created": { "type": "string" }, "date_updated": { "type": "string" }, "date_closed": { "type": [ "string", "null" ] }, "date_done": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "creator": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/creator" }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "color": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "profilePicture": { "type": [ "string", "null" ] } } } }, "group_assignees": { "type": "array", "items": { "type": "object" } }, "watchers": { "type": "array", "items": { "type": "object" } }, "checklists": { "type": "array", "items": { "type": "object" } }, "tags": { "type": "array", "items": { "type": "object" } }, "parent": { "type": [ "string", "null" ] }, "top_level_parent": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "points": { "type": [ "number", "null" ] }, "time_estimate": { "type": [ "number", "null" ] }, "time_spent": { "type": [ "number", "null" ] }, "custom_fields": { "type": "array", "items": { "$ref": "#/paths/~1v2~1task~1{task_id}/get/responses/200/content/application~1json/schema/properties/custom_fields/items" } }, "dependencies": { "type": "array", "items": { "type": "object" } }, "linked_tasks": { "type": "array", "items": { "type": "object" } }, "locations": { "type": "array", "items": { "type": "object" } }, "url": { "type": "string" } }, "example": { "id": "86d2m1awy", "custom_item_id": 0, "name": "Reproduce the issue on staging", "status": { "status": "to do", "orderindex": 0, "color": "#f8ae00", "type": "open" }, "orderindex": "237672022.00000000000000000000000000000000", "date_created": "1775848408603", "date_updated": "1775848408603", "date_closed": null, "date_done": null, "archived": false, "creator": { "id": 183, "username": "Alex Johnson", "color": "#595d66", "email": "user@company.com", "profilePicture": null }, "assignees": [], "group_assignees": [], "watchers": [], "checklists": [], "tags": [], "parent": "9hx", "top_level_parent": "9hx", "due_date": null, "start_date": null, "points": null, "time_estimate": null, "time_spent": 0, "custom_fields": [], "dependencies": [], "linked_tasks": [], "locations": [], "url": "https://app.clickup.com/t/86d2m1awy" } } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "integer", "format": "int64" }, "title": { "type": "string" }, "type": { "type": "integer" }, "source": { "type": "integer" }, "version": { "type": "integer" }, "extension": { "type": "string" }, "thumbnail_small": { "type": "string" }, "thumbnail_medium": { "type": "string" }, "thumbnail_large": { "type": "string" }, "is_folder": { "type": "boolean" }, "mimetype": { "type": "string" }, "hidden": { "type": "boolean" }, "parent_id": { "type": "string" }, "size": { "type": "integer", "format": "int64" }, "total_comments": { "type": "integer" }, "resolved_comments": { "type": "integer" }, "user": { "title": "User2", "type": "object", "properties": { "id": { "type": "integer", "contentEncoding": "int32" }, "username": { "type": "string" }, "initials": { "type": "string" }, "email": { "type": "string" }, "color": { "type": "string" }, "profilePicture": { "type": "string" } }, "examples": [ { "id": 183, "username": "John Doe", "initials": "JD", "email": "user@company.com", "color": "#827718", "profilePicture": "https://attachments-public.clickup.com/profilePictures/183_abc.jpg" } ] }, "deleted": { "type": "boolean" }, "orientation": { "type": "string" }, "url": { "type": "string" }, "email_data": { "type": "object" }, "url_w_query": { "type": "string" }, "url_w_host": { "type": "string" } } } } } } } } } }, "deprecated": false }, "parameters": [] } }, "components": { "securitySchemes": { "Authorization_Token": { "name": "Authorization", "type": "apiKey", "in": "header", "description": "API token required for authentication. Two types of tokens are supported:\n**Personal API Key** Obtain from ClickUp's settings page under 'Apps' and add it to the header as `Authorization: pk_...`\n**OAuth2 Access Token** Generated through the OAuth2 flow and add it to the header as `Authorization: Bearer {access_token}`" } } }, "security": [ { "Authorization_Token": [] } ], "tags": [ { "name": "Tasks" } ] } ```