API v1 Reference

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.

Request
1curl -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.

Request
1curl -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.

Get more help

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