## 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](/projecttemplates) 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`.
```sh title="Request" {5}
curl -X POST "https://api.awork.com/api/v1/projects" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "My new project"
}'
```
### Creating a project with a workflow
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.
```sh title="Request" {6-7}
curl -X POST "https://api.awork.com/api/v1/projects" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "My workflow-based project",
"workflowId": "223e4567-e89b-12d3-a456-426614174000",
"projectStatusId": "323e4567-e89b-12d3-a456-426614174000"
}'
```
### Getting valid statuses for workflow-based project creation
Before creating a project with `workflowId`, fetch the workflow statuses and pick a valid `projectStatusId`.
```sh title="Get workflow project statuses"
curl -X GET "https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/projectstatuses" \
-H "Authorization: Bearer {token}"
```
```sh title="Get workflow task statuses"
curl -X GET "https://api.awork.com/api/v1/workflows/223e4567-e89b-12d3-a456-426614174000/taskstatuses" \
-H "Authorization: Bearer {token}"
```
### Getting valid statuses for an existing project
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.
```sh title="Get valid project statuses for a project"
curl -X GET "https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/projectstatuses" \
-H "Authorization: Bearer {token}"
```
```sh title="Get valid task statuses for a project"
curl -X GET "https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/taskstatuses" \
-H "Authorization: Bearer {token}"
```
### 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.
```sh title="Request" {6}
curl -X POST "https://api.awork.com/api/v1/projects" \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "My new project from a template",
"projectTemplateId": "123e4567-e89b-12d3-a456-426614174000"
}'
```
### 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:
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/comments \
-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"message": "This is a comment on the project"
}'
```
### 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.
```sh title="Request"
curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/comments \
-H "Authorization: Bearer {token}" \
-H 'Content-Type: application/json' \
-d '{
"message": "~[userId:123e4567-e89b-12d3-a456-426614174000] Take a look at this project
" }' ``` 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: ```sh title="Request" curl -X POST https://api.awork.com/api/v1/projects/123e4567-e89b-12d3-a456-426614174000/comments \ -H "Authorization: Bearer {token}" \ -H 'Content-Type: application/json' \ -d '{ "message": "~[project] This will notify all users in this project
" }' ``` 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](https://support.awork.com/en/articles/creating-a-new-project-JNKI2Fpdql6g) in awork.