For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
SupportDeveloper ForumLogin
  • Overview
    • Introduction
    • Getting Started
    • Integration Example (PSA)
    • Authentication
    • Error Handling
    • Pagination
    • Filtering
    • Ordering
    • Rate Limits
    • Permissions
    • Webhooks
    • MCP Server
    • Versioning
    • Changelog
    • Support
  • API v1 Reference
    • Projects Overview
    • Tasks Overview
      • POSTCreates a new project or private task.
      • POSTInvites a user by email and assigns them to a task.
      • POSTEdits multiple tasks using the specified operation.
      • POSTChanges the base type for multiple tasks.
      • POSTChanges the lists of tasks.
      • POSTChanges statuses of tasks.
      • POSTChanges the parent task and the order of subtasks.
      • POSTConvert subtasks to a parent task.
      • POSTChanges the type of work for a batch of tasks.
      • POSTDeletes tasks and optionally related time entries.
      • GETReturns the task with the specified key.
      • POSTSets the priority flag for a task.
      • GETReturns the task with the specified id.
      • PUTUpdates the task with the specified id.
      • POSTCreates a copy of the specified task.
      • POSTDeletes the recurrence rule for a task.
      • GETGets the recurrence rule of a task.
      • POSTAssigns a list of users to a task.
      • POSTModifies planned efforts for the given task assignments.
      • POSTAdds or updates a recurrence rule for a task.
      • POSTUpdates the order of a task within its list.
    • Time Tracking Overview
    • Documents Overview
    • Search Overview
    • Companies Overview
    • Users Overview
    • Files & Images Overview
    • Custom Fields Overview
    • Workload & Planning Overview
    • Project Templates Overview
    • Workflows Overview
    • Login & Access Overview
    • API Management Overview
LogoLogo
SupportDeveloper ForumLogin
API v1 ReferenceTasks

Creates a new project or private task.

POST
https://api.awork.com/api/v1/tasks
POST
/api/v1/tasks
$curl -X POST https://api.awork.com/api/v1/tasks \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "name": "Create logo concept",
>  "baseType": "projecttask"
>}'
1{
2  "name": "Create logo concept",
3  "description": "We need to create a new impactful concept for the customer logo",
4  "isPrio": true,
5  "startOn": "2023-03-03T17:00:00Z",
6  "dueOn": "2023-03-18T17:00:00Z",
7  "laneOrder": 1,
8  "plannedDuration": 21600,
9  "id": "123e4567-e89b-12d3-a456-426614174000",
10  "taskNumber": 1,
11  "taskIdentifier": "string",
12  "isExternal": true,
13  "createdVia": "string",
14  "isHiddenForConnectUsers": true,
15  "baseType": "projecttask",
16  "taskStatusId": "123e4567-e89b-12d3-a456-426614174000",
17  "taskStatus": {
18    "id": "123e4567-e89b-12d3-a456-426614174000",
19    "name": "Conceptualize",
20    "type": "progress",
21    "order": 2,
22    "icon": "arrow_forward",
23    "projectId": "123e4567-e89b-12d3-a456-426614174000",
24    "projectTypeId": "123e4567-e89b-12d3-a456-426614174000",
25    "workflowId": "123e4567-e89b-12d3-a456-426614174000",
26    "createdOn": "2022-03-{10}T15:51:58.100Z",
27    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
28    "updatedOn": "2022-03-10T16:15:26.100Z",
29    "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
30    "isExternal": true
31  },
32  "typeOfWorkId": "123e4567-e89b-12d3-a456-426614174000",
33  "typeOfWork": {
34    "id": "123e4567-e89b-12d3-a456-426614174000",
35    "name": "Design",
36    "icon": "thumb_up",
37    "isArchived": false
38  },
39  "assignees": [
40    {
41      "id": "123e4567-e89b-12d3-a456-426614174000",
42      "firstName": "Carla",
43      "lastName": "Creative",
44      "hasImage": true,
45      "plannedEffort": 1,
46      "isDistributedPlannedEffort": true,
47      "updatedOn": "2020-02-30T18:52:54.945Z",
48      "isExternal": true
49    }
50  ],
51  "projectId": "123e4567-e89b-12d3-a456-426614174000",
52  "project": {
53    "id": "123e4567-e89b-12d3-a456-426614174000",
54    "name": "Design",
55    "projectKey": "string",
56    "projectStatus": {
57      "id": "123e4567-e89b-12d3-a456-426614174000",
58      "name": "Design",
59      "description": "Work in progress",
60      "type": "todo",
61      "isArchived": false
62    },
63    "company": {
64      "id": "123e4567-e89b-12d3-a456-426614174000",
65      "name": "Design",
66      "hasImage": true,
67      "description": "NCNSTN Brand Design Company"
68    },
69    "companyId": "123e4567-e89b-12d3-a456-426614174000",
70    "projectType": {
71      "id": "123e4567-e89b-12d3-a456-426614174000",
72      "name": "Design",
73      "icon": "thumb_up",
74      "isArchived": false
75    },
76    "hasImage": true,
77    "isPrivate": true,
78    "isBillableByDefault": true,
79    "members": [
80      {
81        "id": "123e4567-e89b-12d3-a456-426614174000",
82        "userId": "123e4567-e89b-12d3-a456-426614174000",
83        "projectRoleId": "123e4567-e89b-12d3-a456-426614174000",
84        "projectRoleName": "string",
85        "isResponsible": true,
86        "isExternal": true
87      }
88    ],
89    "color": "purple",
90    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
91    "teams": [
92      {
93        "id": "123e4567-e89b-12d3-a456-426614174000"
94      }
95    ],
96    "customFields": [
97      {
98        "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
99        "userIdValue": "123e4567-e89b-12d3-a456-426614174000",
100        "clientIdValue": "123e4567-e89b-12d3-a456-426614174000",
101        "numberValue": 123.45,
102        "selectionOptionIdValue": "123e4567-e89b-12d3-a456-426614174000",
103        "selectionOption": {
104          "value": "Website Design",
105          "id": "123e4567-e89b-12d3-a456-426614174000",
106          "color": "purple",
107          "order": 0
108        },
109        "textValue": "S1: Business Critical",
110        "dateValue": "2024-01-15T09:30:00Z",
111        "booleanValue": true
112      }
113    ],
114    "isExternal": true
115  },
116  "correlationId": "123e4567-e89b-12d3-a456-426614174000",
117  "parentId": "123e4567-e89b-12d3-a456-426614174000",
118  "parentTask": {
119    "id": "123e4567-e89b-12d3-a456-426614174000",
120    "name": "Design",
121    "createdBy": "123e4567-e89b-12d3-a456-426614174000",
122    "userId": "123e4567-e89b-12d3-a456-426614174000",
123    "assigneeIds": [
124      "string"
125    ]
126  },
127  "isSubtask": true,
128  "numberOfSubtasks": 1,
129  "hasAttachment": false,
130  "lists": [
131    {
132      "id": "123e4567-e89b-12d3-a456-426614174000",
133      "createdOn": "2021-03-22T15:00:00Z",
134      "createdBy": "123e4567-e89b-12d3-a456-426614174000",
135      "updatedOn": "2021-03-22T16:30:00Z",
136      "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
137      "name": "Product and Marketing To-Dos",
138      "order": 2,
139      "plannedDuration": 1,
140      "totalPlannedDuration": 1,
141      "totalPlannedDurationWithHierarchy": 1,
142      "isArchived": false,
143      "isHiddenForConnectUsers": true,
144      "orderOfTask": 5
145    }
146  ],
147  "userId": "123e4567-e89b-12d3-a456-426614174000",
148  "tags": [
149    {
150      "id": "123e4567-e89b-12d3-a456-426614174000",
151      "name": "Design",
152      "color": "purple"
153    }
154  ],
155  "createdOn": "2022-02-29T18:52:54.945Z",
156  "createdBy": "123e4567-e89b-12d3-a456-426614174000",
157  "updatedOn": "2020-02-30T18:52:54.945Z",
158  "updatedBy": "123e4567-e89b-12d3-a456-426614174000",
159  "closedOn": "2024-01-15T09:30:00Z",
160  "closedBy": "123e4567-e89b-12d3-a456-426614174000",
161  "order": 2,
162  "subtaskOrder": 1,
163  "createdFromTaskId": "123e4567-e89b-12d3-a456-426614174000",
164  "isRecurring": true,
165  "customFields": [
166    {
167      "customFieldDefinitionId": "123e4567-e89b-12d3-a456-426614174000",
168      "userIdValue": "123e4567-e89b-12d3-a456-426614174000",
169      "clientIdValue": "123e4567-e89b-12d3-a456-426614174000",
170      "numberValue": 123.45,
171      "selectionOptionIdValue": "123e4567-e89b-12d3-a456-426614174000",
172      "selectionOption": {
173        "value": "Website Design",
174        "id": "123e4567-e89b-12d3-a456-426614174000",
175        "color": "purple",
176        "order": 0
177      },
178      "textValue": "S1: Business Critical",
179      "dateValue": "2024-01-15T09:30:00Z",
180      "booleanValue": true
181    }
182  ],
183  "trackedDuration": 1200,
184  "totalTrackedDuration": 1200,
185  "totalPlannedDuration": 21600,
186  "resourceVersion": 637825154598030700,
187  "checklistItemsDoneCount": 2,
188  "checklistItemsCount": 5,
189  "taskSchedulesCount": 1,
190  "isCompletelyScheduled": true,
191  "commentCount": 1,
192  "entityId": "123e4567-e89b-12d3-a456-426614174000"
193}
<Check title="Required Permissions" icon="key">The user mast either have `project-planning-data:write` permissions, be assigned to the parent task (if a parent task is specified) or create a private task.</Check>
Was this page helpful?
Previous

Invites a user by email and assigns them to a task.

Next
Built with
Required Permissions
The user mast either have project-planning-data:write permissions, be assigned to the parent task (if a parent task is specified) or create a private task.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

The general Task Post form payload.
namestringRequired0-1000 characters

The name of the task. Max allowed length: 1000 characters.

baseTypeenumRequired
The base type of the task. Can be 'private' for a private task or 'projecttask' for a project task.
Allowed values:
descriptionstring or nullOptional0-25000 characters

The description of the task. Max allowed length: 25000 characters.

isPrioboolean or nullOptional
Whether this task is marked as priority.
startOnstring or nullOptionalformat: "date-time"
The expected start date and time of the task.
dueOnstring or nullOptionalformat: "date-time"
The expected due date and time of the task.
laneOrderinteger or nullOptional
The lane order defines the vertical position in the task board.
plannedDurationinteger or nullOptional
The expected planned workload of the task, in seconds.
typeOfWorkIdstring or nullOptionalformat: "uuid"
The id of the type of work for this task. If not provided, defaults to the first type of work in the workspace.
taskStatusIdstring or nullOptionalformat: "uuid"
The id of the status for this task. If not provided, defaults to the first status of type 'todo'.
orderdouble or nullOptional
The order of the task in a task status column.
subtaskOrderdouble or nullOptional
The order of the subtask relative to its parent task.
entityIdstring or nullOptionalformat: "uuid"
The id of the entity the task is related to. For private tasks, this is optional and will default to the current user's ID if not provided. For project tasks, this is required and must be the project ID.
parentIdstring or nullOptionalformat: "uuid"
The id of the parent task. Setting this value means this is a subtask.
listslist of objects or nullOptional

The list(s) the new task should be added to.

Response

OK
namestring0-1000 characters

The name of the task. Max allowed length: 1000 characters.

descriptionstring or null0-25000 characters

The description of the task. Max allowed length: 25000 characters.

isPrioboolean
Whether this task is marked as priority.
startOnstring or nullformat: "date-time"
The expected start date and time of the task.
dueOnstring or nullformat: "date-time"
The expected due date and time of the task.
laneOrderinteger
The lane order defines the vertical position in the task board.
plannedDurationinteger
The expected planned workload of the task, in seconds.
idstringformat: "uuid"
The Id of the task.
taskNumberinteger or null
The sequential task number within the project. Unique within the project, never reused even after deletion.
taskIdentifierstring or null<=40 characters

The full task identifier combining project key and task number (e.g., “NIKE-42”). Maintained by the service layer, updated when project key changes.

isExternalboolean

True if the model is coming from an external workspace (awork Connect). False otherwise.

createdViastring or null
The origin of the task. From which 'flow' the task was created. Automatically set by the backend.
isHiddenForConnectUsersboolean
True if the task is hidden for external workspace users. False otherwise.
baseTypeenum
The base type of the task. Can be 'private' for a private task or 'projecttask' for a project task.
Allowed values:
taskStatusIdstringformat: "uuid"
The id of the status for this task.
taskStatusobject
typeOfWorkIdstringformat: "uuid"
The id of the type of work of this task.
typeOfWorkobject
assigneeslist of objects or null
The list assigned users of this task, or empty if not user was assigned.
projectIdstring or nullformat: "uuid"
The id of the project this task is assigned to. Only set if this is a project task. In this case, it is equal to the EntityId.
projectobject
correlationIdstringformat: "uuid"
The correlation id between parent and subtasks, meaning it's either the ParentId or its own Id.
parentIdstring or nullformat: "uuid"
The id of the parent task this of this subtask. Only set if this is a subtask.
parentTaskobject
isSubtaskbooleanRead-only
True if the task is a subtask.
numberOfSubtasksinteger or null
The number of subtasks of this task. Null if it's not a parent task.
hasAttachmentboolean
Whether this task has an attachment.
listslist of objects or null
The lists to which the task is assigned to.
userIdstring or nullformat: "uuid"
The id of the user of the private task.
tagslist of objects or null
The list of tags.
createdOnstringformat: "date-time"
The date this task was created.
createdBystringformat: "uuid"
The id of the user who created this task.
updatedOnstringformat: "date-time"
The date this task was last modified.
updatedBystringformat: "uuid"
The id of the user who last modified this task.
closedOnstring or nullformat: "date-time"
The date the task was set to closed.
closedBystring or nullformat: "uuid"
The user who closed the task.
orderdouble
The order of the task in a task status column.
subtaskOrderdouble or null
The order of the subtask relative to its parent task.
createdFromTaskIdstring or nullformat: "uuid"
When the task was created by a recurrency rule, the id is the link to the template of which the task was created.
isRecurringboolean

If the task is a recurrency template (used to create new tasks by a recurrency rule), the flag is true.

customFieldslist of objects or null
Custom fields of the task.
trackedDurationinteger or null

The summed up duration of all time trackings directly on this task (excluding subtasks).

totalTrackedDurationinteger or null
The summed up duration of all time trackings for this task, including subtasks.
totalPlannedDurationinteger or null
The total planned workload of the task, in seconds, including subtasks.
resourceVersionlongRead-only
The version of the entity, updated on every modification, to the ticks in UTC. Not identical to UpdatedOn.
checklistItemsDoneCountinteger
The number of checklist items marked as done.
checklistItemsCountinteger
The total number of checklist items.
taskSchedulesCountinteger
The number of task schedules for this task.
isCompletelyScheduledboolean
Whether this task is completed scheduled.
commentCountinteger
The number of comments on this task.
entityIdstring or nullformat: "uuid"Deprecated
The id of the entity this task is assigned to. This is the id of the project if this is a project task, or the id of a user if this is a private task. See 'BaseType' for supported types.

Errors

400
Bad Request Error
401
Unauthorized Error