Create a new track in a project with access checks, optional due date, status, type, step number, and public project URL path support.
The method creates a track inside the specified project. For public projects, it can also associate the created track with a URL path. After successful creation, the method writes an activity log entry and publishes a realtime update.
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_add
Request body:
{
"project_id": 7,
"name": "Development",
"description": "Development tasks for the current release.",
"due_date": "2026-09-30 18:00:00",
"status": "ACTIVE",
"type": "REGULAR",
"step_number": 2,
"session_id": "abc123xyz"
}
In this example:
42 is the organization/account ID.project_id=7 creates the track inside project 7.name defines the track name.description contains an optional track description.due_date defines an optional deadline.status=ACTIVE creates an active track.type=REGULAR creates a regular track.step_number=2 defines the track position/order value.session_id=abc123xyz is used for authentication.
project_idandnameare required.
Required
The method requires a valid authenticated or guest/public access context.
Access rules:
projects_users.public_project_id must match the requested project_id.If the account ID in the URL does not match the account associated with the authorization context, the request will be rejected.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
session_id |
string | Yes* | – | Authenticated user session ID. |
project_id |
int | Yes | – | Project ID where the new track will be created. |
name |
string | Yes | – | Track name. Maximum 128 characters. Longer values are truncated. |
description |
string | No | "" |
Track description. Maximum 1024 characters. Longer values are truncated. |
due_date |
datetime | No | null |
Track due date. Expected format: Y-m-d H:i:s. |
status |
string | No | ACTIVE |
Track status. Allowed values: ACTIVE, REMOVED, DONE. |
type |
string | No | REGULAR |
Track type. Allowed values: REGULAR, TEMPLATE. |
step_number |
int | No | 0 |
Numeric track step/order value. |
URL_PATH |
string | No | null |
URL path associated with the track. Applied only to PUBLIC projects and only if the value passes URL path validation. |
* Authorization may also use the supported guest/public access context.
{
"data": {
"operation_status": "SUCCESS",
"track_id": 123
}
}
track_id contains the ID of the newly created track.
{
"data": {
"operation_status": "FAILED",
"operation_message": "project_id is required"
},
"error_message": "project_id is required",
"error_no": 4403
}
The method creates a new record in the tracks table.
| Field | Type | Description |
|---|---|---|
track_id |
int | Unique track identifier generated after creation. |
project_id |
int | ID of the project containing the track. |
created |
datetime | Date and time when the track was created. |
updated |
datetime | Date and time when the track was created or last updated. |
due_date |
datetime/null | Optional track due date. |
name |
string | Track name, up to 128 characters. |
description |
string | Track description, up to 1024 characters. |
status |
enum | Track status: ACTIVE, REMOVED, or DONE. |
type |
enum | Track type: REGULAR or TEMPLATE. |
step_number |
int | Track step/order value. |
tasks_total |
int | Total task counter. Initialized to 0. |
tasks_opened |
int | Open task counter. Initialized to 0. |
tasks_closed |
int | Closed task counter. Initialized to 0. |
For projects with project_type=PUBLIC, the optional URL_PATH parameter can be used to associate a URL path with the newly created track.
Example:
{
"project_id": 7,
"name": "Homepage",
"URL_PATH": "/products/security/"
}
When the value is valid, an additional record is created for the track with:
track_idsite_idURL_PATHURL_PATH is ignored if:
PUBLIC; orAn invalid URL_PATH does not cause the track_add request itself to fail.
After successful track creation, the method performs several additional actions:
URL_PATH is provided.INSERT event to the WebSocket channel for the current account.Example WebSocket event:
{
"action": "INSERT",
"object": "tracks",
"data": {
"...": "created track data"
}
}
The event is published to:
account:{account_id}
| HTTP Code | error_no |
Message | Description |
|---|---|---|---|
401 |
– | Unauthorized |
Missing or invalid authorization context. |
200 |
4401 |
Project Not Found |
The specified project_id does not exist. |
200 |
4402 |
Access denied |
Regular user or project manager does not have access to the specified project. |
200 |
4403 |
project_id is required |
project_id was not provided. |
200 |
4404 |
due_date wrong format, expected format: Y-m-d H:i:s |
The supplied due_date cannot be parsed. |
200 |
4405 |
name is required |
Track name was not provided. |
200 |
4406 |
status must be in ('ACTIVE','REMOVED','DONE') |
Invalid status value. |
200 |
4407 |
type must be in ('REGULAR','TEMPLATE') |
Invalid type value. |
200 |
2005 |
Access denied |
Guest user has no access to the requested project or does not have a public project context. |
200 |
0 |
Internal API Error |
Internal error or database insert failure. |
name is required and is limited to 128 characters.description is optional and is limited to 1024 characters.due_date is normalized to the Y-m-d H:i:s format before saving.ACTIVE.REGULAR.step_number is 0.tasks_total, tasks_opened, and tasks_closed are initialized to 0.projects_users.URL_PATH functionality is available only for projects with project_type=PUBLIC.URL_PATH values are ignored rather than returning an API error.