Archive a milestone

POST /api/v1/milestones/{milestoneId}/archive

Retires a milestone. It stays on the path, at its place, and accepts no further write.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused

Requirement	Rule for this endpoint
Business role	None — an expected result is retired by whoever may change the program
Resource scope	Milestone of the school attached to the API key
Resource state	An already archived milestone answers `400`

Path parameters

Parameter	Type	Required	Description
`milestoneId`	UUID	yes	Milestone visible from the key's school

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this school
`Idempotency-Key`	yes	Stable key for this archival
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`effectiveAt`	ISO 8601 string	no	no	When the archival takes effect. Defaults to now
`reason`	string	no	yes	Up to 500 characters

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/milestones/$MILESTONE_ID/archive" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Replaced by a shorter milestone."}'

Response

200 OK — the milestone is archived.
400 Bad Request — missing Idempotency-Key, invalid JSON, an invalid date, or a milestone already archived.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN of this school.
404 Not Found — the milestone is unknown or belongs to another school.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "2e6a9c14-8b7d-4f3e-a5c2-0f1a2b3c4d5e",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "title": "First agent in production",
    "objective": "Deploy an agent that answers real users.",
    "expectedProof": "A public URL and a short demo video.",
    "successCriteria": "Three consecutive answers.",
    "status": "archived",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-04T17:12:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Update a milestone

POST /api/v1/milestones/{milestoneId}/archive

Retires a milestone. It stays on the path, at its place, and accepts no further write.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused

Requirement	Rule for this endpoint
Business role	None — an expected result is retired by whoever may change the program
Resource scope	Milestone of the school attached to the API key
Resource state	An already archived milestone answers `400`

Path parameters

Parameter	Type	Required	Description
`milestoneId`	UUID	yes	Milestone visible from the key's school

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this school
`Idempotency-Key`	yes	Stable key for this archival
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`effectiveAt`	ISO 8601 string	no	no	When the archival takes effect. Defaults to now
`reason`	string	no	yes	Up to 500 characters

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/milestones/$MILESTONE_ID/archive" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Replaced by a shorter milestone."}'

Response

200 OK — the milestone is archived.
400 Bad Request — missing Idempotency-Key, invalid JSON, an invalid date, or a milestone already archived.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN of this school.
404 Not Found — the milestone is unknown or belongs to another school.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "2e6a9c14-8b7d-4f3e-a5c2-0f1a2b3c4d5e",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "title": "First agent in production",
    "objective": "Deploy an agent that answers real users.",
    "expectedProof": "A public URL and a short demo video.",
    "successCriteria": "Three consecutive answers.",
    "status": "archived",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-04T17:12:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Update a milestone

Archive a milestone

Archive a milestone

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Related

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Related