API v1 Reference

Tasks

Tasks represent the smallest unit of work in awork. They are used to break down larger chunks of work, track progress, and collaborate with others.

Types of Tasks

There are two types of tasks: project tasks and private tasks. This is identified by the baseType field in the task object, which can be either projecttask or private.

Project Tasks

Project tasks are tasks that are associated with a project and organized in task lists.

Private Tasks

Private tasks are tasks that are associated with a user and are not visible to other users.

Creating a Task

The following properties are required when creating a task:

Request
1curl -X POST https://api.awork.com/api/v1/tasks \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "name": "My first task",
5    "baseType": "projecttask",
6    "typeOfWorkId": "123e4567-e89b-12d3-a456-426614174000",
7    "taskStatusId": "123e4567-e89b-12d3-a456-426614174000",
8    "entityId": "123e4567-e89b-12d3-a456-426614174000"
9  }'

Subtasks

Subtasks have almost the same properties as tasks, but they also have a parentId property that references the parent task. This is how you can create a subtask:

Request
1curl -X POST https://api.awork.com/api/v1/tasks \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "name": "My first task",
5    "baseType": "projecttask",
6    "typeOfWorkId": "123e4567-e89b-12d3-a456-426614174000",
7    "taskStatusId": "123e4567-e89b-12d3-a456-426614174000",
8    "entityId": "123e4567-e89b-12d3-a456-426614174000",
9    "parentId": "123e4567-e89b-12d3-a456-426614174000"
10  }'
The subtask has to be in the same project as the parent task.

Learn more about subtasks here.

Checklist Items

Each task comes with a checklist of simple items that can be checked off. This is how you can create a checklist item:

Request
1curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/checklistItems \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "name": "My first checklist item"
5  }'

Learn more about checklists here.

Task Lists

Tasks can be in one or several task lists. This is how you can add a task to a task list or change the list:

Request
1curl -X POST https://api.awork.com/api/v1/tasks/changelists \
2  -H 'Content-Type: application/json' \
3  -d '[
4	{
5		"taskId": "123e4567-e89b-12d3-a456-426614174000",
6		"taskLists": [
7			{
8				"id": "123e4567-e89b-12d3-a456-426614174000"
9			}
10		]
11	}
12]'

Task Comments

Task comments allow for discussions and communication about tasks. You can add comments to a task using the following endpoint:

Request
1curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/comments \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "message": "This is a comment on the task"
5  }'

Mentioning Users in Comments

You can mention users in comments by using a special syntax with the user’s Id. When a user is mentioned, they will receive a notification based on their notification settings.

Request
1curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/comments \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "message": "<p>~[userId:123e4567-e89b-12d3-a456-426614174000] Take a look at this task</p>"
5  }'

The syntax for mentioning a user is: ~[userId:{userId}] where {userId} is the Id of the user you want to mention.

Notifying Task or Project Watchers

In addition to mentioning specific users, you can notify all users watching a task or project:

Request
1curl -X POST https://api.awork.com/api/v1/tasks/123e4567-e89b-12d3-a456-426614174000/comments \
2  -H 'Content-Type: application/json' \
3  -d '{
4    "message": "<p>~[task] This will notify all users watching this task</p>"
5  }'

You can use:

  • ~[task] to notify all users watching the task
  • ~[project] to notify all users watching the project the task belongs to
  • ~[workspace] to notify all users in the workspace