Update an existing track, including its name, description, project, due date, status, type, step number, favorite labels, favorite label groups, and public project URL path.
The method checks access to the track’s current project and, when moving the track, access to the destination project. A successful update refreshes the track timestamp, publishes a WebSocket update, and may create activity log entries or update related tasks.
The number in the URL path (/1/) is the organization identifier — referred to as account_id.
This value must match the account associated with the provided session_id or token.
This endpoint supports both:
POST https://api.doboard.com/42/track_update
Request body:
{
"track_id": 123,
"name": "Development",
"description": "Development tasks for the current release.",
"due_date": "2026-09-30 18:00:00",
"status": "ACTIVE",
"type": "REGULAR",
"step_number": 2,
"favorite_labels": [5, 8, 12],
"favorite_label_groups": [3, 4],
"session_id": "abc123xyz"
}
In this example:
42 is the organization/account ID.track_id=123 identifies the track to update.name replaces the current track name.description replaces the current description.due_date sets a new deadline.status=ACTIVE sets the track status.type=REGULAR sets the track type.step_number=2 updates its numeric step/order value.favorite_labels replaces the track’s favorite label list.favorite_label_groups replaces the track’s favorite label-group list.session_id=abc123xyz is used for authentication.
track_idis required.
At least one parameter that triggers a track update must be supplied.
Required
The method requires a valid session or guest/public access context:
session_id – for authenticated userstoken – for guest/public accessAccess rules:
projects_users.project_id.If the account ID in the URL does not match the account tied to the session or token, the request will be rejected.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id |
string | Yes* | – | Authenticated user session ID. |
token |
string | Yes* | – | Guest/public access token. |
track_id |
int | Yes | – | ID of the track to update. |
name |
string | No | unchanged | New track name. Cannot be empty when supplied. Maximum 128 characters; longer values are truncated. |
description |
string | No | unchanged | New track description. Maximum 1024 characters; longer values are truncated. An empty value clears the description. |
project_id |
int | No | unchanged | Destination project ID. The project must exist and be accessible to the current user. |
status |
string | No | unchanged | Track status. Allowed values: ACTIVE, REMOVED, DONE. An empty value is ignored. |
due_date |
datetime | No | unchanged | Track due date. Parsed and normalized to Y-m-d H:i:s. An empty value sets it to null. |
type |
string | No | unchanged | Track type. Allowed values: REGULAR, TEMPLATE. An empty value is ignored. |
step_number |
int | No | unchanged | Numeric track step/order value. Capped at 4294967295. |
URL_PATH |
string | No | unchanged | URL path associated with the track in a public project. Subject to the conditions described below. |
favorite_labels |
int / array / string | No | unchanged | Replaces the track’s favorite labels. Accepts a single ID, an array, or comma-separated IDs. An empty value clears the list. |
favorite_label_groups |
int / array / string | No | unchanged | Replaces the track’s favorite label groups. Accepts a single ID, an array, or comma-separated IDs. An empty value clears the list. |
* Either session_id or token is required.
{
"data": {
"operation_status": "SUCCESS",
"track_id": 123
}
}
The response returns the updated track ID but does not include the complete updated track object.
{
"data": {
"operation_status": "FAILED",
"operation_message": "track_id is required"
},
"error_message": "track_id is required",
"error_no": 4701
}
Validation and access errors defined by this method are returned with HTTP status 200. Authentication failure uses HTTP status 401.
When at least one recognized update operation is present, the corresponding record in the tracks table is updated.
| Field | Update behavior |
|---|---|
updated |
Set to the current server time whenever the track update runs. |
name |
Replaced with the supplied value, up to 128 characters. |
description |
Replaced with the supplied value, up to 1024 characters. |
project_id |
Replaced with the validated destination project ID. |
status |
Replaced with ACTIVE, REMOVED, or DONE. |
due_date |
Replaced with the normalized date or set to null. |
type |
Replaced with REGULAR or TEMPLATE. |
step_number |
Replaced with the converted integer value, capped at 4294967295. |
Missing parameters leave their corresponding fields unchanged.
Supplying a recognized field with its existing value still refreshes the track’s updated timestamp, although no change-specific activity entry is created for that field.
When a valid project_id different from the current project is supplied:
If the supplied project_id is the same as the current project, destination access checks still run, but related tasks and project totals are not updated.
The following track statuses are accepted:
ACTIVEDONEREMOVEDWhen the status changes, an activity action is created:
| New status | Activity action |
|---|---|
ACTIVE |
Track was reopened. |
DONE |
Track was completed. |
REMOVED |
Track was deleted. |
When status=REMOVED is supplied, every task belonging to the track is also updated to REMOVED.
This related-task update runs even if the track was already in REMOVED status.
Changing the track to ACTIVE or DONE does not change the statuses of its tasks.
URL_PATH is accepted only when all of the following are true:
project_type=PUBLIC.^/[\w\-\.~%?&=+@\#/]*$
After the main track update succeeds, the method creates or updates the track’s public URL-path record with:
track_idsite_idURL_PATHImportant behavior:
URL_PATH does not trigger the main track update by itself.Empty input with error 4711.URL_PATH is applied only when another parameter causes the track update to run.URL_PATH does not delete or clear an existing URL-path record.project_id and URL_PATH are supplied together, URL-path validation and site association use the track’s original project rather than the destination project.When favorite_labels is supplied, the track’s existing favorite labels are removed before the new list is applied.
The value may be:
The supplied values are converted to IDs, filtered, deduplicated, and checked against existing labels.
Only label IDs that exist are applied. An empty value clears all favorite labels. Supplying only unknown or invalid IDs also leaves the track with no favorite labels.
When favorite_label_groups is supplied, it replaces the track’s existing favorite label groups.
The parameter accepts a single group ID, an array, or comma-separated IDs. Only existing group IDs are applied. An empty value clears all favorite label groups.
After a successful track update, the method may perform these additional actions:
URL_PATH is available.REMOVED when status=REMOVED.REMOVED.Example WebSocket event:
{
"action": "UPDATE",
"object": "tracks",
"data": {
"...": "updated track data"
}
}
No activity action is created for changes limited to:
typestep_numberfavorite_labelsfavorite_label_groupsURL_PATHThe method prepares notification descriptions for status and due-date changes, but no notification delivery is performed in this method.
| HTTP Code | error_no |
Message | Description |
|---|---|---|---|
401 |
– | Unauthorized |
Missing or invalid session/token. |
200 |
4701 |
track_id is required |
track_id was not provided or was empty. |
200 |
4702 |
Track Not Found |
The specified track does not exist or is not associated with a project. |
200 |
4703 |
Access denied |
A non-admin user does not have access to the track’s current project. |
200 |
4704 |
name is required |
name was supplied but is empty. |
200 |
4705 |
Project Not Found |
The supplied destination project does not exist. |
200 |
4706 |
Access is denied |
A non-admin, non-guest user does not have access to the destination project. |
200 |
4706 |
Access denied |
A guest has no public project context, or the destination project does not match it. |
200 |
4707 |
project_id is required |
project_id was supplied but is empty. |
200 |
4708 |
status must be in ('ACTIVE','REMOVED','DONE') |
A non-empty unsupported status was supplied. |
200 |
4709 |
due_date wrong format, expected format: Y-m-d H:i:s |
The supplied due date could not be parsed. |
200 |
4710 |
type must be in ('REGULAR','TEMPLATE') |
A non-empty unsupported type was supplied. |
200 |
4711 |
Empty input |
No parameter that triggers the main track update was supplied. |
200 |
0 |
Internal API Error |
The main track update failed. |
track_id is mandatory and cannot be changed.name cannot be cleared, while description can be cleared.due_date removes the existing due date.status and type are processed only when their values are non-empty.REMOVED also sets all of its tasks to REMOVED.ACTIVE does not restore its tasks.URL_PATH alone is treated as empty input and cannot clear an existing URL-path record.