Skip to main content
POST
Create a milestone
Creates a milestone on an existing roadmap and workstream (otherwise 404 resource_missing). Send name, roadmapId, workstreamId, quarter (YYYY-QN), ownerKind, ownerRefId, and optionally description, targetDate (epoch milliseconds), rank (default: the end of its roadmap quarter), isRelease (default false), releaseVersion and status (default PLANNED). 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 201 with the PlanningMilestone. Without an Idempotency-Key, repeating a create creates a second record. 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 List milestones.

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

Body

application/json

A milestone on an existing roadmap and workstream, in a YYYY-QN quarter; PLANNED and at the end of its roadmap quarter unless given. Unknown fields are refused.

name
string
required

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

Maximum string length: 200
roadmapId
string
required

The roadmap ID, as the planning reads return it.

Required string length: 1 - 200
workstreamId
string
required

The workstream ID, as the planning reads return it.

Required string length: 1 - 200
quarter
string
required

The Blueprint quarter, YYYY-QN (for example 2026-Q3).

Pattern: ^\d{4}-Q[1-4]$
ownerKind
enum<string>
required

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

Available options:
company,
department,
team
ownerRefId
string
required

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

Required string length: 1 - 200
description
string

At most 4,000 characters.

Maximum string length: 4000
targetDate
number

When the milestone is due, epoch milliseconds.

rank
number

Position within the roadmap quarter; defaults to the end of that quarter.

isRelease
boolean

Whether the milestone is a release; default false.

releaseVersion
string

The release version, at most 100 characters.

Maximum string length: 100
status
enum<string>

Defaults to PLANNED.

Available options:
PLANNED,
IN_PROGRESS,
COMPLETE,
CANCELLED

Response

Create a milestone

data
object
required
meta
object
required