Skip to main content

​
Milestones

The Milestones API provides CRUD access to project milestones plus bulk reordering.
New to the API? Start with Getting started (base URL, response envelope, errors, pagination) and Authentication (API keys).
Identifier note: milestones are addressed by their numeric milestone_id.
Milestones belong to a project. They are grouping buckets that tasks are assigned to. Listing requires a project_id. Each project has a system uncategorised default milestone (the catch-all for tasks without one) which cannot be deleted.
Scope: the global milestone-category templates (settings/milestones) and web events are out of API scope.

​
The milestone object

{
  "id": 690,
  "title": "Phase 1",
  "project_id": 159,
  "type": "categorised",
  "color": "success",
  "position": 1,
  "creator_id": 1,
  "tasks_count": 4,
  "dates": { "created": "...", "updated": "..." }
}
FieldTypeNotes
idintegerMilestone id.
titlestring
project_idintThe owning project.
typestringcategorised, or uncategorised (the system default).
colorstringA colour key (e.g. default, success, warning, danger).
positionintOrdering position.
tasks_countintNumber of tasks in the milestone.

​
List milestones

GET /api/milestones?project_id={project_id}
project_id is required. Other query params: type, search, sort (milestone_title,milestone_position,milestone_created), order, limit, page. 
curl -G https://your-domain/api/milestones -H "Authorization: Bearer YOUR_API_KEY" -d project_id=159

​
Get a milestone

GET /api/milestones/{id}

​
Create a milestone

POST /api/milestones
ParameterTypeRequiredNotes
milestone_projectidintegeryesThe project.
milestone_titlestringyesMust be unique within the project.
milestone_colorstringyesA colour key.
curl -X POST https://your-domain/api/milestones -H "Authorization: Bearer YOUR_API_KEY" \
  -d milestone_projectid=159 -d milestone_title="Phase 1" -d milestone_color=success
Returns the new milestone (201, type categorised).

​
Update a milestone

PATCH /api/milestones/{id}
Only the title and colour are editable (the project and type are immutable).
ParameterTypeRequired
milestone_titlestringyes
milestone_colorstringyes

​
Delete a milestone

DELETE /api/milestones/{id}
The system uncategorised default cannot be deleted (409). By default the milestone’s tasks are reassigned to the project’s default milestone; pass delete_tasks=yes to delete the tasks instead (along with their attachments/comments/timers).
ParameterTypeNotes
delete_tasksstringyes to delete the tasks; otherwise they are reassigned.

​
Reorder milestones

PUT /api/milestones/positions
Sets each milestone’s position from the supplied ordered list of ids (1..N).
ParameterTypeRequired
milestones[]array of intsyes
curl -X PUT https://your-domain/api/milestones/positions -H "Authorization: Bearer YOUR_API_KEY" \
  -d "milestones[]=12" -d "milestones[]=10" -d "milestones[]=15"

​
Errors

See Getting started. Milestone-specific:
StatusMeaning
404 Not FoundThe milestone id does not exist.
409 ConflictDuplicate title in the project, or attempting to delete the system default.
422 Unprocessable EntityValidation failed (missing project_id on list, missing fields, or an invalid project).