Create a milestone

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

Defines a milestone at the end of the program's main path. The path is resolved — and created if this is the first milestone — by the platform: you never create one yourself.

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 defined 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 creation intention
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`title`	string	yes	no	3 to 100 characters
`objective`	string	no	yes	The objective, up to 2000 characters
`expectedProof`	string	no	yes	What the member submits, up to 2000 characters
`successCriteria`	string	no	yes	What makes it a success, up to 2000 characters

json

{
  "title": "First agent in production",
  "objective": "Ship an agent that answers real users.",
  "expectedProof": "A public URL and the run log of one real conversation.",
  "successCriteria": "The agent answers three consecutive questions without a human."
}

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/programs/$PROGRAM_ID/milestones" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"title":"First agent in production"}'

Response

201 Created — the milestone exists, last on the path.
200 OK — the same Idempotency-Key replayed the original creation.
400 Bad Request — missing Idempotency-Key, invalid JSON, or a title outside 3–100 characters.
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,
  "replayed": false,
  "data": {
    "id": "2e6a9c14-8b7d-4f3e-a5c2-0f1a2b3c4d5e",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "title": "First agent in production",
    "objective": null,
    "expectedProof": null,
    "successCriteria": null,
    "status": "active",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Notes

The milestone, its place on the path, the audit entry and the milestone.created event are written in one transaction.
No email or notification is sent by this endpoint.

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

Defines a milestone at the end of the program's main path. The path is resolved — and created if this is the first milestone — by the platform: you never create one yourself.

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 defined 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 creation intention
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`title`	string	yes	no	3 to 100 characters
`objective`	string	no	yes	The objective, up to 2000 characters
`expectedProof`	string	no	yes	What the member submits, up to 2000 characters
`successCriteria`	string	no	yes	What makes it a success, up to 2000 characters

json

{
  "title": "First agent in production",
  "objective": "Ship an agent that answers real users.",
  "expectedProof": "A public URL and the run log of one real conversation.",
  "successCriteria": "The agent answers three consecutive questions without a human."
}

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/programs/$PROGRAM_ID/milestones" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"title":"First agent in production"}'

Response

201 Created — the milestone exists, last on the path.
200 OK — the same Idempotency-Key replayed the original creation.
400 Bad Request — missing Idempotency-Key, invalid JSON, or a title outside 3–100 characters.
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,
  "replayed": false,
  "data": {
    "id": "2e6a9c14-8b7d-4f3e-a5c2-0f1a2b3c4d5e",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "title": "First agent in production",
    "objective": null,
    "expectedProof": null,
    "successCriteria": null,
    "status": "active",
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-01T09:00:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Notes

The milestone, its place on the path, the audit entry and the milestone.created event are written in one transaction.
No email or notification is sent by this endpoint.

Create a milestone

Create a milestone

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Notes

Related

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Notes

Related