Reorder the milestones of a program

POST /api/v1/programs/{programId}/milestones/reorder

Sets the order of the main path of a program. The complete ordered list, never a move: the ids you send must be exactly the milestones of that path.

Authorization

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

Requirement	Rule for this endpoint
Business role	None — the path is ordered by whoever may change the program
Resource scope	Program of the school attached to the API key
Resource state	An archived program refuses every write, and answers `403`

Path parameters

Parameter	Type	Required	Description
`programId`	UUID	yes	Program 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 ordering
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`orderedMilestoneIds`	array of UUID	yes	no	1 to 500 ids, no duplicates, exactly the milestones of the main path

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/programs/$PROGRAM_ID/milestones/reorder" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"orderedMilestoneIds":["'"$FIRST"'","'"$SECOND"'"]}'

Response

200 OK — the milestones, in their new order.
400 Bad Request — missing Idempotency-Key, invalid JSON, duplicates, an empty list, or a set that is not exactly the milestones of the path.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN, or the program is archived.
404 Not Found — the program is unknown or belongs to another school.

Example response

json

{
  "success": true,
  "data": [
    {
      "id": "7f3c5b28-4a1e-4d6b-8c93-1a2b3c4d5e6f",
      "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
      "title": "Agent with memory",
      "objective": null,
      "expectedProof": null,
      "successCriteria": null,
      "status": "active",
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-04T17:12:00.000Z"
    },
    {
      "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": "active",
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-04T17:12:00.000Z"
    }
  ],
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

List the milestones of a program

With Idempotency-Key, retries of the identical target and payload do not write another mutation, audit or event. A different intention under that key returns 409. Results describe the currently authorized resource state.

POST /api/v1/programs/{programId}/milestones/reorder

Sets the order of the main path of a program. The complete ordered list, never a move: the ids you send must be exactly the milestones of that path.

Authorization

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

Requirement	Rule for this endpoint
Business role	None — the path is ordered by whoever may change the program
Resource scope	Program of the school attached to the API key
Resource state	An archived program refuses every write, and answers `403`

Path parameters

Parameter	Type	Required	Description
`programId`	UUID	yes	Program 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 ordering
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`orderedMilestoneIds`	array of UUID	yes	no	1 to 500 ids, no duplicates, exactly the milestones of the main path

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/programs/$PROGRAM_ID/milestones/reorder" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"orderedMilestoneIds":["'"$FIRST"'","'"$SECOND"'"]}'

Response

200 OK — the milestones, in their new order.
400 Bad Request — missing Idempotency-Key, invalid JSON, duplicates, an empty list, or a set that is not exactly the milestones of the path.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN, or the program is archived.
404 Not Found — the program is unknown or belongs to another school.

Example response

json

{
  "success": true,
  "data": [
    {
      "id": "7f3c5b28-4a1e-4d6b-8c93-1a2b3c4d5e6f",
      "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
      "title": "Agent with memory",
      "objective": null,
      "expectedProof": null,
      "successCriteria": null,
      "status": "active",
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-04T17:12:00.000Z"
    },
    {
      "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": "active",
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-04T17:12:00.000Z"
    }
  ],
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

List the milestones of a program

Reorder the milestones of a program

Reorder the milestones of a program

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Related

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Related