Milestones

Create and manage milestones to track release targets. Link test runs, monitor progress, and organize sub-milestones.

Milestone object fields

Parameter	Type	Required	Description
id	string	No	Unique milestone identifier
name	string	Yes	Milestone name
description	string	No	Optional description
start_date	string (ISO 8601)	No	Start date of the milestone
due_date	string (ISO 8601)	No	Target due date
status	string	No	One of: upcoming, started, past_due, completed. Read-only if sub milestones exist (auto-derived).
parent_milestone_id	string	No	Parent milestone ID for sub-milestones (max 1 level nesting)
date_mode	string	No	"auto" = dates derived from sub milestones; "manual" = manually set. Default: "auto".
progress	number	No	Completion percentage (0-100). Auto-aggregated from sub milestones if they exist.
created_at	string (ISO 8601)	No	Creation timestamp
updated_at	string (ISO 8601)	No	Last update timestamp

GET/v1/projects/:project_id/milestones

List milestones

Retrieve all milestones for a project. Optionally filter by status.

Query parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: active, completed, or archived
page	number	No	Page number for pagination (default: 1)
per_page	number	No	Items per page (default: 20, max: 100)

Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.testably.app/v1/projects/proj_abc123/milestones?status=active"

Response 200 OK

{
  "data": [
    {
      "id": "ms_001",
      "name": "v2.0 Release",
      "description": "Major release with new dashboard",
      "start_date": "2026-03-01T00:00:00Z",
      "due_date": "2026-04-15T00:00:00Z",
      "status": "active",
      "parent_id": null,
      "progress": 68,
      "created_at": "2026-02-28T10:00:00Z",
      "updated_at": "2026-03-28T14:22:00Z"
    }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1 }
}

GET/v1/projects/:project_id/milestones/:id

Get milestone detail

Retrieve a single milestone including linked test runs and progress percentage.

Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.testably.app/v1/projects/proj_abc123/milestones/ms_001"

Response 200 OK

{
  "id": "ms_001",
  "name": "v2.0 Release",
  "description": "Major release with new dashboard",
  "start_date": "2026-03-01T00:00:00Z",
  "due_date": "2026-04-15T00:00:00Z",
  "status": "active",
  "parent_id": null,
  "progress": 68,
  "linked_runs": [
    {
      "id": "run_101",
      "name": "Regression Suite",
      "status": "in_progress",
      "pass_rate": 72
    },
    {
      "id": "run_102",
      "name": "Smoke Test",
      "status": "completed",
      "pass_rate": 100
    }
  ],
  "sub_milestones": [
    {
      "id": "ms_002",
      "name": "v2.0 - API",
      "status": "completed",
      "progress": 100
    }
  ],
  "created_at": "2026-02-28T10:00:00Z",
  "updated_at": "2026-03-28T14:22:00Z"
}

POST/v1/projects/:project_id/milestones

Create milestone

Create a new milestone. Provide a parent_id to create a sub-milestone.

Request body

Parameter	Type	Required	Description
name	string	Yes	Milestone name
description	string	No	Optional description
start_date	string (ISO 8601)	No	Start date
due_date	string (ISO 8601)	No	Target due date
parent_id	string	No	Parent milestone ID to create as sub-milestone

Request

curl -X POST \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "v2.1 Hotfix",
       "description": "Critical bug fixes",
       "due_date": "2026-04-20T00:00:00Z",
       "parent_id": "ms_001"
     }' \
     "https://api.testably.app/v1/projects/proj_abc123/milestones"

Response 201 Created

{
  "id": "ms_003",
  "name": "v2.1 Hotfix",
  "description": "Critical bug fixes",
  "start_date": null,
  "due_date": "2026-04-20T00:00:00Z",
  "status": "active",
  "parent_id": "ms_001",
  "progress": 0,
  "created_at": "2026-03-29T09:15:00Z",
  "updated_at": "2026-03-29T09:15:00Z"
}

PATCH/v1/projects/:project_id/milestones/:id

Update milestone

Update milestone fields. Only include fields you want to change.

Request body

Parameter	Type	Required	Description
name	string	No	Updated milestone name
description	string	No	Updated description
start_date	string (ISO 8601)	No	Updated start date
due_date	string (ISO 8601)	No	Updated due date
status	string	No	Change status: active, completed, or archived

Request

curl -X PATCH \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "status": "completed" }' \
     "https://api.testably.app/v1/projects/proj_abc123/milestones/ms_001"

Response 200 OK

{
  "id": "ms_001",
  "name": "v2.0 Release",
  "description": "Major release with new dashboard",
  "start_date": "2026-03-01T00:00:00Z",
  "due_date": "2026-04-15T00:00:00Z",
  "status": "completed",
  "parent_id": null,
  "progress": 100,
  "created_at": "2026-02-28T10:00:00Z",
  "updated_at": "2026-03-29T10:30:00Z"
}

Error responses

Status	Description
400	Invalid request body or query parameters
401	Missing or invalid API token
403	Insufficient permissions
404	Project or milestone not found
429	Rate limit exceeded (60 req/min)