> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Milestones

> Read, maintain and rerank Blueprint milestones over the Platform API.

A milestone is a delivery checkpoint placed in a `YYYY-QN` quarter on a roadmap and a workstream. Reads use the `objectives:read` scope and require that permission at the deployment root. Writes use the `projects:manage` scope together with `objectives:read` and require both permissions at the deployment root. A milestone's `category` is readable; it and its human override are written only in the Console, because the GitHub to Blueprint sync must not re-derive a person's choice. A tenant-only grant receives `403 permission_denied`.

## Operations

* [List milestones](https://docs.gloo.com/forge/reference/http-api/milestones/list.md) — a roadmap's or workstream's in rank order, or by release flag; cursor paging up to 100 rows
* [Get milestone](https://docs.gloo.com/forge/reference/http-api/milestones/get.md) — one milestone by id

## Write operations

* [Create milestone](https://docs.gloo.com/forge/reference/http-api/milestones/create.md) — on an existing roadmap and workstream
* [Update milestone](https://docs.gloo.com/forge/reference/http-api/milestones/update.md) — fields, quarter moves and objective tags; `CANCELLED` archives
* [Rerank milestones](https://docs.gloo.com/forge/reference/http-api/milestones/rerank.md) — ranks 0, 1, 2, … in the given order

Milestones are never deleted over the API. A quarter move that would break a task dependency is `409 conflict` with a fixed message, and nothing is written. Every write accepts an optional `Idempotency-Key`. A same-key retry within 24 hours returns the recorded result only while the caller still holds `objectives:read` and `projects:manage` at the deployment root; otherwise `409 idempotency_result_unavailable`, and the write never runs twice. A successful write records no audit event, as the Console's planning writes record none; a refused write records a denial.

List cursors are bound to the filters that created them. Reusing one with different filters returns `400 bad_request`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.