> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.awork.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.awork.com/_mcp/server.

# Changelog

> This page contains a list of past and upcoming changes the the awork API.

This page contains a list of past and upcoming changes to the awork API. We always try our best to prevent breaking changes, but sometimes we can't avoid making some changes in order to release a new awesome feature. 🚀

> **Warning**
>
> Breaking Changes are marked with 🚨

[Subscribe](https://awork.typeform.com/to/ZAQrwnkH) to API updates and other developer news.

## Upcoming changes

This section shows upcoming changes.

🚨 Upcoming deprecations for API models:

* The `RemainingDuration` and `TotalRemainingDuration` properties of the `TaskModel` are deprecated and will be removed at the end of the year.

### Workflows: project and task statuses can be shared across projects 🚨

With the [Workflows feature](https://www.awork.com/roadmap), project and task statuses can now be inherited from a workflow and shared across all projects linked to that workflow.

As a result, integrations that fetch statuses and filter by `projectId` only can miss relevant statuses. Status models can now return `workflowId` instead of `projectId`.

> **Warning**
>
> Latest rollout deadline for affected ERP/custom integrations: **July 31, 2026**.\
>
> Upgrade your integration before **July 31, 2026** to avoid issues.

Rollout note:

* For workspaces with known ERP or custom integrations, the Workflows feature can remain deactivated until **July 31, 2026** at the latest.
* Integrations should be upgraded before **July 31, 2026** to avoid issues when Workflows are enabled.
* Workflows can be enabled earlier on request once the integration is ready.
* [Please let us know](https://support.awork.com/en/articles/getting-help-WS8JSOzZrf8a) once your integration has been updated or verified to be compatible, so we can enable Workflows for workspaces using that integration.

Why this is breaking:

* Previously, integrations often filtered status lists by `projectId`.
* With workflow-based statuses, `projectId` can be `null` and `workflowId` is set.
* Task statuses from different projects can now have the same `id` when those projects use the same workflow.
* If your client aggregates task statuses from multiple projects into one list and keys by `id` only, this can lead to duplicate entries/collisions.

Project status example before:

```json
{
  "id": "8b10f329-4cf3-42a5-a216-4560e318db8f",
  "name": "In Progress",
  "projectId": "3e664818-9503-4ec8-9f1f-35d5ad7a57ad",
  "workflowId": null
}
```

Project status example with Workflows:

```json
{
  "id": "0f5f3318-8024-4b0b-a748-7e8ed6f13a60",
  "name": "In Progress",
  "projectId": null,
  "workflowId": "49f36ad2-9372-4ce2-a697-9ece6126d5cf"
}
```

Task status example with Workflows:

```json
{
  "id": "4e4e6c4f-b4b0-449a-85ad-c6fcf3443b72",
  "name": "Review",
  "projectId": null,
  "workflowId": "49f36ad2-9372-4ce2-a697-9ece6126d5cf"
}
```

### Migration path

#### Recommended path

Use project or project-template scoped endpoints to fetch statuses.

#### Recommended migration path

> **Recommended**
>
> Switch to entity-specific endpoints to fetch statuses.

* For project statuses, use `GET /projects/{projectId}/projectstatuses`.
* For task statuses, use `GET /projects/{projectId}/taskstatuses`.
* For project template statuses, use `GET /projecttemplates/{projectTemplateId}/projectstatuses`.
* For project template task statuses, use `GET /projecttemplates/{projectTemplateId}/taskstatuses`.
* These endpoints return statuses relevant for the requested project or project template, regardless of whether they are entity-specific or inherited from the linked workflow.
* `GET /projecttemplates` can now return nested `projectStatuses` that are inherited from the linked workflow.
* Complete this migration before **July 31, 2026** if your workspace currently has Workflows deactivated due to ERP/custom integrations.

**`Project statuses for a specific project`**

```sh title="Project statuses for a specific project"
curl -X GET "https://api.awork.com/api/v1/projects/3e664818-9503-4ec8-9f1f-35d5ad7a57ad/projectstatuses" \
  -H "Authorization: Bearer {token}"
```

**`Project statuses response example if the project does not use workflows`**

```json title="Project statuses response example if the project does not use workflows"
[
  {
    "id": "8b10f329-4cf3-42a5-a216-4560e318db8f",
    "name": "In Progress",
    "projectId": "3e664818-9503-4ec8-9f1f-35d5ad7a57ad",
    "workflowId": null
  }
]
```

**`Project statuses response example if the project uses workflows`**

```json title="Project statuses response example if the project uses workflows"
[
  {
    "id": "0f5f3318-8024-4b0b-a748-7e8ed6f13a60",
    "name": "In Progress",
    "projectId": null,
    "workflowId": "49f36ad2-9372-4ce2-a697-9ece6126d5cf"
  }
]
```

**`Task statuses for a specific project`**

```sh title="Task statuses for a specific project"
curl -X GET "https://api.awork.com/api/v1/projects/3e664818-9503-4ec8-9f1f-35d5ad7a57ad/taskstatuses" \
  -H "Authorization: Bearer {token}"
```

**`Project statuses for a specific project template`**

```sh title="Project statuses for a specific project template"
curl -X GET "https://api.awork.com/api/v1/projecttemplates/3e664818-9503-4ec8-9f1f-35d5ad7a57ad/projectstatuses" \
  -H "Authorization: Bearer {token}"
```

**`Task statuses for a specific project template`**

```sh title="Task statuses for a specific project template"
curl -X GET "https://api.awork.com/api/v1/projecttemplates/3e664818-9503-4ec8-9f1f-35d5ad7a57ad/taskstatuses" \
  -H "Authorization: Bearer {token}"
```

> **Info**
>
> Project and task statuses can either have the `projectId` or `workflowId` set, depending on whether they are project or workflow specific. Project template statuses can either have the `projectTemplateId` or `workflowId` set, depending on whether they are template-specific or inherited from a workflow.

### Questions and support

If you have any questions or need support, please lets us know to our [awork Community Developer Forum](https://community.awork.com/c/developer-forum/17).

## Recent changes

This section shows you recent changes that are already live in our API.

### Edge security update 🔐

We updated our edge security configuration, which might lead to some invalid or suspicious requests to be blocked with a `403 Forbidden` status code. Please check your API request if this is the case. Should you need any help, please contact us in the developer forum and provide us with the `X-Edge-Ref` and `Trace-Id` header values where available.

### New: Retainer projects 🚀

Retainer budgets have been a highly requested feature in awork that we are finally releasing. Retainer budgets help you manage recurring time budgets for projects. As part of the release, the Project model gets a new property `isRetainer` which is set to `true` if the project has at least one retainer budget. You can retrieve the retainers of a project via the new `GET /projects/{projectId}/retainers` endpoint.
Managing retainers is currently only possible via the web app.

> **Note**
>
> 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.

### New: Custom Fields 🚀

Custom fields is one of the most highly requested features in awork. They allow users to add custom properties to tasks via projects and project templates. Custom fields can be of different types, such as text, number, date, and more.

They are also a great way to store additional information in tasks, such as an external Id, which makes it a lot easier to integrate awork with other tools via the API.

See the [Custom Fields Overview & API Reference](./customfields) for more information.

### Domain changed to awork.com: clients need to update URLs 🚨

We have recently switched our primary domain from `awork.io` to `awork.com`. The application and website remain available at both domains for the time being, however, **by end of December 2023**, clients must have updated to `awork.com` to continue using the awork API.

[Find more details here](https://support.awork.com/en/articles/8333169-awork-switches-to-com).

### Projects, Tasks and Users: Key and NumberCount properties removed 🚨

The `Key` property of Projects, Tasks and Users as well as the `NumberCount` property of Tasks have been removed. These properties were never used in the awork web app, so we're removing them from the API models as well.

These changes are happening in the API on **26.05.2023 in the evening**.

### Tasks: EntityId is deprecated 🚨

The `EntityId` in the Task model is deprecated and will be removed in the future. Use `UserId` for private tasks and `ProjectId` for project tasks instead.

These changes are happening in the API on **05.05.2023 in the evening**.

### Tasks: several nested fields removed 🚨

The following nested fields have been removed from the model for performance reasons:

```
Task.Project.Teams
Task.Project.Tags
Task.Company.Tags
Task.Assignees.Teams
Task.Assignees.Tags
```

These changes are happening in the API on **05.05.2023 in the evening**.

### Subtasks become Checklists 🚨

We are adding a new feature called Subtasks, therefore we are renaming the currently existing Subtasks to Checklists. The new Subtasks will be more powerful and bring a new level of planning to awork.

In the following endpoints, `subtasks` will be renamed to `checklists`. The functionality remains the same.

This change is happening in the API on **03.03.2023 in the evening**.

### API Rate Limits for API clients  🚨

We are introducing API rate limits that will limit the number of requests external API clients can make to a workspace. These limits depend on the plan of the workspace. The limits are shared by all external client applications across the workspace. Please see [Rate Limits](/rate-limits) for details.

This change is happening in the API on **03.03.2023 in the evening**.

### Workload calculation - Single user calculation removal  🚨

We are deprecating the endpoint

`GET /users/{userId}/workload`

in favour of the new one:

`GET /users/workload`

This new endpoint will provide multiple user results in a single request, plus it has the option to fetch the details of the workload calculation.

The legacy endpoint will still be active up to **01.01.2023.** \
Then it will be removed.

### Project Member Capacity - Endpoints removal 🚨

With the introduction of the project time bookings, we are migrating all the project member capacities to them.

As such, all the related endpoints are being deprecated and will not have any meaningful effect on the workload calculations:

* `GET /projects/{projectId}/members/{projectMemberId}/capacity`
* `PUT /projects/{projectId}/members/{projectMemberId}/capacity`
* `GET /projects/{projectId}/members/capacities`

We will remove those endpoints and the related data starting from **01.01.2023**

### User Capacity - Property Removed New Endpoint 🚨

The `User` model currently has a `CapacityPerWeek` property, which we're removing soon. This property is getting it's own endpoint: `/users/{userId}/capacity`

This endpoint has `GET` and `PUT` methods to retrieve and edit the user's weekly capacity. The `GET` model looks like this:

```json
{
  "userId": "b9fd0955-9252-4746-aba5-f6b82ba24d56",
  "capacityPerWeek": 144000
}
```

For a short time, both the property and the new endpoints will exist in parallel to be backward-compatible. We will remove the old property starting in **March 2022**. Please update your API client accordingly.

### Project Templates - Auto Billability 🚨

Currently, projects have one property called `IsBillableByDefault` ,which decides whether time entries created on that project are marked as billable or not. This is either set by the project template, or if no project template was used for creation, by whether the project has a company or not. In the case of a company, the times are marked as billed, otherwise the times are marked as not billable.

The problem is, that the project template always overrules this company rule. We need to have more flexibility here, so we change the `IsBillableByDefault` property on the project template from a `boolean` to a `string` field with the possible values: `on, off, auto`.

When the `auto` option is set, the `IsBillableByDefault` of the project on project creation will be set according to the company rule, so `true` if a company is set and `false` if no company is set.

### Multi-User Assignment - 18.09.21 🚨

This release adds the highly requested feature to assign multiple users to the same task. As a result, we reworked the endpoints that allow assigning multiple users to tasks and task templates as well as automations.

If you want to use this feature, please enable the task setting "Allow multi-user assignment" in awork in the workspace settings page. Alternatively, you can activate the setting by calling the tasks/settings endpoint from below with the setting name `allow-multi-user-assignment`.

### Older Changes

Older changes can be found in the release articles on our roadmap [https://www.awork.com/roadmap/](https://www.awork.com/roadmap) 🕵🏻‍♂️