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.
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 is easy. The only required field for creating a project is the name.
You can create and link a project to a workflow directly in POST /projects by passing workflowId.
If needed, you can also pass a valid projectStatusId from that workflow.
Before creating a project with workflowId, fetch the workflow statuses and pick a valid projectStatusId.
Use project-scoped endpoints to fetch the statuses that are valid for one specific project. These endpoints already return the correct set, including workflow-inherited statuses when the project is linked to a workflow.
To create a project from a project template, the projectTemplateId has to be passed in the POST /projects request.
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.
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.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 allow for discussions and communication about projects. You can add comments to a project using the following endpoint:
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.
The syntax for mentioning a user is: ~[userId:{userId}] where {userId} is the Id of the user you want to mention.
In addition to mentioning specific users, you can notify all members of a project:
You can use:
~[project] to notify all members of this project~[workspace] to notify all users in the workspaceMake sure to check out our dedicated support page on getting started with projects in awork.