Skip to main content
PATCH
Update a milestone
Changes a milestone’s name, description, quarter, targetDate, isRelease, releaseVersion, status, owner or objectiveIds (up to 100; each must exist, otherwise 404 resource_missing); send id and at least one field. Status CANCELLED archives it. A quarter change moves the milestone to the end of the target quarter; when that would break a task dependency it is 409 conflict with a fixed message naming only the quarter, and nothing is written. The category and its human override are not writable. The credential needs both the projects:manage and objectives:read scopes, and objectives:read and projects:manage granted at the deployment root; otherwise 403 permission_denied names the first missing permission and nothing is written. The body is strict: unknown fields are 400 bad_request. Success is 200 with the PlanningMilestone. With a key, a same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise 409 idempotency_result_unavailable, and the write never runs twice. Reconcile an unknown outcome with Get milestone.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

milestoneId
string
required

The milestone ID, as the planning reads return it.

Required string length: 1 - 200

Body

application/json

The fields to change; omitted fields are unchanged. At least one field besides id is required. Unknown fields are refused. Set status CANCELLED to archive. The category and its human override are not writable here.

name
string

Stored exactly as sent; at most 200 characters and not blank.

Maximum string length: 200
description
string

At most 4,000 characters.

Maximum string length: 4000
quarter
string

Moves the milestone to the end of this quarter, unless that breaks a task dependency.

Pattern: ^\d{4}-Q[1-4]$
targetDate
number

When the milestone is due, epoch milliseconds.

isRelease
boolean
releaseVersion
string

The release version, at most 100 characters.

Maximum string length: 100
status
enum<string>

CANCELLED archives the milestone.

Available options:
PLANNED,
IN_PROGRESS,
COMPLETE,
CANCELLED
ownerKind
enum<string>

Who owns it: the company, a department or a team. Never a person.

Available options:
company,
department,
team
ownerRefId
string

The owning company, department or team identifier, recorded as sent.

Required string length: 1 - 200
objectiveIds
string[]

Replaces the objectives the milestone serves; each must exist. At most 100.

Maximum array length: 100

The objective ID, as the planning reads return it.

Required string length: 1 - 200

Response

Update a milestone

data
object
required
meta
object
required