Login / Register
POST
/api/public/v1/milestones

Create a milestone

Add a grouping inside one project. Names are unique within that project — a duplicate is refused rather than creating a second milestone. In the console this is a project manager’s job: the milestone list is how everyone’s work is grouped, so adding to it is not a side effect of being able to write your own. A `projects:write` token passes the same rule as the employee it acts as: it needs to be a manager of the project.

Required scope

The access token must carry this scope. A token missing it gets 403 Forbidden. Grant them to an API client under Dev Tools → API, to an assistant or CLI sign-in when you approve or edit it under Dev Tools, and to a teammate under Employee → Permissions.

projects:write

Request Body

PropertyTypeDescription
projectIdstringThe project the milestone belongs to. Milestones do not span projects.
namestringUnique within the project.
colorstringOne of the shared palette keys.
ownerIdstringActive employee of this company. The owner and the project’s managers are the only ones who may later edit it.
descriptionstringWhat the milestone covers.
startAtstringISO 8601 — the day the work starts. Together with `endsAt`, this is what puts it on the roadmap. Store it at midday: these are calendar days held as instants, and a midnight boundary reads as the previous day west of UTC.
endsAtstringISO 8601 — the day the work ends. Must not be earlier than `startAt`.
POSTExample request
curl
curl -X POST "https://www.pxb.app/api/public/v1/milestones" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_a1b2c3",
    "name": "Billing",
    "color": "violet",
    "ownerId": "emp_12ab"
  }'
200Example response
json
{
  "message": "Milestone created successfully!",
  "content": {
    "milestone": {
      "id": "epc_9f8e",
      "name": "Billing",
      "description": "Everything invoicing-related for the rebuild.",
      "color": "violet",
      "status": "IN_PROGRESS",
      "startAt": "2026-07-01T12:00:00.000Z",
      "endsAt": "2026-09-30T12:00:00.000Z",
      "order": 0,
      "projectId": "prj_a1b2c3",
      "projectKey": "APOLLO",
      "projectName": "Apollo billing rebuild",
      "owner": {
        "employeeId": "emp_12ab",
        "name": "Sam Okafor",
        "email": "sam@example.com",
        "avatarUrl": null
      },
      "ticketCount": 6,
      "createdAt": "2026-06-02T10:00:00.000Z"
    }
  }
}
409Example response
json
{
  "message": "A milestone with that name already exists here."
}

In the console

The same thing done by hand, for anyone comparing the API against the screen they already use.

Projects → Milestones
/projects
  1. Open a project.
  2. Milestones → Manage milestones.