Create or Update Task

Creates a new task or updates an existing one if ID is provided

Query Parameters

expand?|||array<>

Expansion fields: "all" (full enrichment, default), "none" (IDs only), or comma-separated/repeated fields (status,area,project,assignee)

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

id?string

Task ID (optional, will be generated if not provided)

name*string

Task name (required)

areaId?string

Area ID (optional, defaults to user's default area in workspace)

statusId?string

Status ID (optional, defaults to area's 'not started' status)

description?|

Task description, accepts markdown

dueDate?||

Due date (Unix seconds or ISO timestamp with timezone)

startDate?||

Start date (Unix seconds or ISO timestamp with timezone)

priority?boolean

Priority flag

assignedToId?|

Assignee user ID or username

projectId?|

Project ID or handle

parentTaskId?|

Parent task ID. Null detaches; omission preserves the parent on update. Subtasks inherit parent area and project.

visibility?string

Task visibility

labelIds?array<>

Label IDs to attach to task. When provided, replaces all existing labels. Omit to leave labels unchanged.

Response Body

`application/json`

curl -X POST "https://example.com/v1/tasks" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "dueDate": "2019-08-24T14:15:22Z",  "completedAt": "2019-08-24T14:15:22Z",  "publicId": 0,  "priority": true,  "visibility": "string",  "createdById": "e13e432a-5323-4484-a91d-b5969bc564d9",  "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",  "areaId": "ebbb2a49-d827-4796-8d8a-108c229835e9",  "statusId": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "deletedAt": "2019-08-24T14:15:22Z",  "startDate": "2019-08-24T14:15:22Z",  "assignedToId": "7a15e53b-1403-4928-9451-d7062c3a8737",  "repeatId": "cef73cf7-0158-4282-a1d8-86ad6c8f41a9",  "description": {    "html": "string",    "markdown": "string"  },  "pathId": "string",  "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4",  "status": {    "id": "string",    "name": "string",    "stage": "string",    "color": "string"  },  "assignee": {    "id": "string",    "name": "string",    "email": "string",    "username": "string"  },  "area": {    "id": "string",    "name": "string",    "publicId": "str"  },  "project": {    "id": "string",    "name": "string",    "publicId": "string",    "slug": "string"  },  "labels": [    {      "id": "string",      "color": "icon-secondary",      "name": "string"    }  ],  "descriptionSnapshot": {    "descriptionStateStr": "string",    "descriptionMarkdown": "string"  },  "parent": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "dueDate": "2019-08-24T14:15:22Z",    "completedAt": "2019-08-24T14:15:22Z",    "publicId": 0,    "priority": true,    "visibility": "string",    "createdById": "e13e432a-5323-4484-a91d-b5969bc564d9",    "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",    "areaId": "ebbb2a49-d827-4796-8d8a-108c229835e9",    "statusId": "string",    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "deletedAt": "2019-08-24T14:15:22Z",    "startDate": "2019-08-24T14:15:22Z",    "assignedToId": "7a15e53b-1403-4928-9451-d7062c3a8737",    "repeatId": "cef73cf7-0158-4282-a1d8-86ad6c8f41a9",    "description": {      "html": "string",      "markdown": "string"    },    "pathId": "string",    "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4",    "status": {      "id": "string",      "name": "string",      "stage": "string",      "color": "string"    },    "assignee": {      "id": "string",      "name": "string",      "email": "string",      "username": "string"    },    "area": {      "id": "string",      "name": "string",      "publicId": "str"    },    "project": {      "id": "string",      "name": "string",      "publicId": "string",      "slug": "string"    },    "labels": [      {        "id": "string",        "color": "icon-secondary",        "name": "string"      }    ]  },  "subtasks": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "dueDate": "2019-08-24T14:15:22Z",      "completedAt": "2019-08-24T14:15:22Z",      "publicId": 0,      "priority": true,      "visibility": "string",      "createdById": "e13e432a-5323-4484-a91d-b5969bc564d9",      "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",      "areaId": "ebbb2a49-d827-4796-8d8a-108c229835e9",      "statusId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "deletedAt": "2019-08-24T14:15:22Z",      "startDate": "2019-08-24T14:15:22Z",      "assignedToId": "7a15e53b-1403-4928-9451-d7062c3a8737",      "repeatId": "cef73cf7-0158-4282-a1d8-86ad6c8f41a9",      "description": {        "html": "string",        "markdown": "string"      },      "pathId": "string",      "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4",      "status": {        "id": "string",        "name": "string",        "stage": "string",        "color": "string"      },      "assignee": {        "id": "string",        "name": "string",        "email": "string",        "username": "string"      },      "area": {        "id": "string",        "name": "string",        "publicId": "str"      },      "project": {        "id": "string",        "name": "string",        "publicId": "string",        "slug": "string"      },      "labels": [        {          "id": "string",          "color": "icon-secondary",          "name": "string"        }      ]    }  ],  "dependsOn": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "dueDate": "2019-08-24T14:15:22Z",      "completedAt": "2019-08-24T14:15:22Z",      "publicId": 0,      "priority": true,      "visibility": "string",      "createdById": "e13e432a-5323-4484-a91d-b5969bc564d9",      "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",      "areaId": "ebbb2a49-d827-4796-8d8a-108c229835e9",      "statusId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "deletedAt": "2019-08-24T14:15:22Z",      "startDate": "2019-08-24T14:15:22Z",      "assignedToId": "7a15e53b-1403-4928-9451-d7062c3a8737",      "repeatId": "cef73cf7-0158-4282-a1d8-86ad6c8f41a9",      "description": {        "html": "string",        "markdown": "string"      },      "pathId": "string",      "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4",      "status": {        "id": "string",        "name": "string",        "stage": "string",        "color": "string"      },      "assignee": {        "id": "string",        "name": "string",        "email": "string",        "username": "string"      },      "area": {        "id": "string",        "name": "string",        "publicId": "str"      },      "project": {        "id": "string",        "name": "string",        "publicId": "string",        "slug": "string"      },      "labels": [        {          "id": "string",          "color": "icon-secondary",          "name": "string"        }      ]    }  ],  "requiredBy": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "dueDate": "2019-08-24T14:15:22Z",      "completedAt": "2019-08-24T14:15:22Z",      "publicId": 0,      "priority": true,      "visibility": "string",      "createdById": "e13e432a-5323-4484-a91d-b5969bc564d9",      "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",      "areaId": "ebbb2a49-d827-4796-8d8a-108c229835e9",      "statusId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "deletedAt": "2019-08-24T14:15:22Z",      "startDate": "2019-08-24T14:15:22Z",      "assignedToId": "7a15e53b-1403-4928-9451-d7062c3a8737",      "repeatId": "cef73cf7-0158-4282-a1d8-86ad6c8f41a9",      "description": {        "html": "string",        "markdown": "string"      },      "pathId": "string",      "parentTaskId": "2506db93-67fe-4ab8-a809-f4aa6ed8a0f4",      "status": {        "id": "string",        "name": "string",        "stage": "string",        "color": "string"      },      "assignee": {        "id": "string",        "name": "string",        "email": "string",        "username": "string"      },      "area": {        "id": "string",        "name": "string",        "publicId": "str"      },      "project": {        "id": "string",        "name": "string",        "publicId": "string",        "slug": "string"      },      "labels": [        {          "id": "string",          "color": "icon-secondary",          "name": "string"        }      ]    }  ],  "comments": [    {      "id": "string",      "publicId": "string",      "content": "string",      "action": "string",      "actionValue": "string",      "entityId": "string",      "entityType": "string",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "ownerId": "string",      "parentId": "string",      "isResolved": true,      "sourceType": null,      "sourceUrl": null,      "sourceMetadata": {},      "entityTitle": "string",      "entityUrl": "string",      "postUrl": "string",      "files": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "publicId": "string",          "url": "http://example.com",          "kind": "avatar",          "visibility": "public",          "name": "string",          "contentType": "string",          "size": 0,          "width": 0,          "height": 0,          "status": "pending",          "entityType": "post",          "entityId": "string",          "createdAt": "2019-08-24T14:15:22Z"        }      ],      "reactions": [        {          "id": "string",          "postId": "string",          "userId": "string",          "reaction": "string"        }      ],      "owner": {        "id": "string",        "name": "string",        "email": "string",        "username": "string"      },      "replies": [        {          "id": "string",          "publicId": "string",          "content": "string",          "action": "string",          "actionValue": "string",          "entityId": "string",          "entityType": "string",          "createdAt": "2019-08-24T14:15:22Z",          "updatedAt": "2019-08-24T14:15:22Z",          "ownerId": "string",          "parentId": "string",          "isResolved": true,          "sourceType": null,          "sourceUrl": null,          "sourceMetadata": {},          "entityTitle": "string",          "entityUrl": "string",          "postUrl": "string",          "files": [            {              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",              "publicId": "string",              "url": "http://example.com",              "kind": "avatar",              "visibility": "public",              "name": "string",              "contentType": "string",              "size": 0,              "width": 0,              "height": 0,              "status": "pending",              "entityType": "post",              "entityId": "string",              "createdAt": "2019-08-24T14:15:22Z"            }          ],          "reactions": [            {              "id": "string",              "postId": "string",              "userId": "string",              "reaction": "string"            }          ],          "owner": {            "id": "string",            "name": "string",            "email": "string",            "username": "string"          }        }      ],      "repliesHasMore": true    }  ]}

Query Parameters

Request Body

Response Body

200application/json

`application/json`