Projects

Projects are one of the core entities in the awork API. They represent a collection of tasks and other resources that are related to a specific project. Projects can be used to organize work, track progress, and collaborate with others in awork.

How to work with projects

There are two major ways for creating a project in awork: using a project template or from scratch. See the Project Template endpoint for more information on how to manage project templates.

Creating a project from scratch

Creating a project from scratch is easy. The only required field for creating a project is the name.

1
curl -X POST "https://api.awork.com/api/v1/projects" \
2
     -H "Content-Type: application/json" \
3
     -d '{
4
           "name": "My new project"
5
         }'

Creating a project from a template

To create a project from a project template, the projectTemplateId has to be passed in the POST /projects request.

1
curl -X POST "https://api.awork.com/api/v1/projects" \
2
     -H "Content-Type: application/json" \
3
     -d '{
4
           "name": "My new project from a template",
5
           "projectTemplateId": "123e4567-e89b-12d3-a456-426614174000"
6
         }'

Working with retainer projects

Retainer projects are projects which have at least one retainer budget. They have the isRetainer property set to true. The timebudget property of a retainer project cannot be updated manually but instead shows the sum of all timebudgets of all retainer budgets of the project. In order to turn a retainer project back to a one-off budget, all retainer budgets have to be deleted.

Calculated properties

The following properties are calculated and cannot be set manually:

• trackedDuration -> The sum of the duration of all time entries of the project. If the deductNonBillableHours property of the project is set to false, only time entries with isBillable set to true are included in the calculation.
• plannedDuration -> The sum of plannedDuration of all tasks of the project.
• tasksCount -> The number of tasks of the project.
• tasksDoneCount -> The number of tasks of the project which are done.
• Special case for timebudget: The timebudget property of a retainer project cannot be updated manually but instead shows the sum of all timebudgets of all retainer budgets of the project.

Project Comments

Project comments allow for discussions and communication about projects. You can add comments to a project using the following endpoint:

1
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/comments \
2
  -H 'Content-Type: application/json' \
3
  -d '{
4
    "message": "This is a comment on the project"
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.

1
curl -X POST https://api.awork.com/api/v1/projects/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 project</p>"
5
  }'

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

Notifying Project Members

In addition to mentioning specific users, you can notify all members of a project:

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

You can use:

• ~[project] to notify all members of this project
• ~[workspace] to notify all users in the workspace

Get more help

Make sure to check out our dedicated support page on getting started with projects in awork.