Create a cohort

POST /api/v1/cohorts

Creates a cohort of a program. A cohort is born draft and moves forward with Change a cohort's status. Dates are optional — an evergreen program has none.

Authorization

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

Requirement	Rule for this endpoint
Business role	None
Resource scope	The program belongs to the key's organization
Participation	None
Resource state	The program is not archived

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this organization
`Idempotency-Key`	yes	Stable key for this creation; a replay returns the first cohort
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`programId`	UUID	yes	no	Program of the key's organization
`name`	string	yes	no	3 to 100 characters
`startDate`	string	no	yes	Calendar date, `YYYY-MM-DD`
`endDate`	string	no	yes	Calendar date, `YYYY-MM-DD`, not before `startDate`
`timezone`	string	yes	no	IANA time zone, for example `Europe/Paris`

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/cohorts" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: cohort-autumn-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "9f2c4a10-8f7e-4a3b-9c1d-2e5f6a7b8c9d",
    "name": "Autumn cohort",
    "startDate": "2026-10-05",
    "endDate": "2026-12-18",
    "timezone": "Europe/Paris"
  }'

Response

201 Created — the cohort, in draft.
200 OK — replayed: true: the key was already used, the original cohort comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a name out of bounds, an unknown time zone, an end date before the start date, or a program that is not in this school.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer is not OWNER or ADMIN, or the program is archived.

Response fields

Field	Type	Description
`data.id`	UUID	Cohort id
`data.programId`	UUID	Program of the cohort
`data.name`	string	Cohort name
`data.status`	string	`draft` at creation
`data.startDate` / `data.endDate`	string	ISO dates, or `null`
`data.timezone`	string	IANA time zone
`data.capacity`	integer	`null` — unlimited until you configure it
`data.occupancy`	integer	Seats taken, `0` at creation
`data.overCapacity`	boolean	`false` at creation
`data.phases[]`	array	Empty at creation

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "programId": "9f2c4a10-8f7e-4a3b-9c1d-2e5f6a7b8c9d",
    "name": "Autumn cohort",
    "status": "draft",
    "startDate": "2026-10-05T00:00:00.000Z",
    "endDate": "2026-12-18T00:00:00.000Z",
    "timezone": "Europe/Paris",
    "capacity": null,
    "occupancy": 0,
    "overCapacity": false,
    "phases": []
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Agent recipe

POST /api/v1/cohorts — the cohort, draft.
PATCH /api/v1/cohorts/{cohortId} — capacity and phases, if the program has any.
POST /api/v1/cohorts/{cohortId}/status with {"status": "open"}.
POST /api/v1/enrollments — one per person.

Notes

The cohort emits a cohort.created event, delivered to your webhook subscriptions.
A replay with the same Idempotency-Key returns the original cohort without a second row or event.

POST /api/v1/cohorts

Creates a cohort of a program. A cohort is born draft and moves forward with Change a cohort's status. Dates are optional — an evergreen program has none.

Authorization

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

Requirement	Rule for this endpoint
Business role	None
Resource scope	The program belongs to the key's organization
Participation	None
Resource state	The program is not archived

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this organization
`Idempotency-Key`	yes	Stable key for this creation; a replay returns the first cohort
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`programId`	UUID	yes	no	Program of the key's organization
`name`	string	yes	no	3 to 100 characters
`startDate`	string	no	yes	Calendar date, `YYYY-MM-DD`
`endDate`	string	no	yes	Calendar date, `YYYY-MM-DD`, not before `startDate`
`timezone`	string	yes	no	IANA time zone, for example `Europe/Paris`

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/cohorts" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: cohort-autumn-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "programId": "9f2c4a10-8f7e-4a3b-9c1d-2e5f6a7b8c9d",
    "name": "Autumn cohort",
    "startDate": "2026-10-05",
    "endDate": "2026-12-18",
    "timezone": "Europe/Paris"
  }'

Response

201 Created — the cohort, in draft.
200 OK — replayed: true: the key was already used, the original cohort comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a name out of bounds, an unknown time zone, an end date before the start date, or a program that is not in this school.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer is not OWNER or ADMIN, or the program is archived.

Response fields

Field	Type	Description
`data.id`	UUID	Cohort id
`data.programId`	UUID	Program of the cohort
`data.name`	string	Cohort name
`data.status`	string	`draft` at creation
`data.startDate` / `data.endDate`	string	ISO dates, or `null`
`data.timezone`	string	IANA time zone
`data.capacity`	integer	`null` — unlimited until you configure it
`data.occupancy`	integer	Seats taken, `0` at creation
`data.overCapacity`	boolean	`false` at creation
`data.phases[]`	array	Empty at creation

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "programId": "9f2c4a10-8f7e-4a3b-9c1d-2e5f6a7b8c9d",
    "name": "Autumn cohort",
    "status": "draft",
    "startDate": "2026-10-05T00:00:00.000Z",
    "endDate": "2026-12-18T00:00:00.000Z",
    "timezone": "Europe/Paris",
    "capacity": null,
    "occupancy": 0,
    "overCapacity": false,
    "phases": []
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Agent recipe

POST /api/v1/cohorts — the cohort, draft.
PATCH /api/v1/cohorts/{cohortId} — capacity and phases, if the program has any.
POST /api/v1/cohorts/{cohortId}/status with {"status": "open"}.
POST /api/v1/enrollments — one per person.

Notes

The cohort emits a cohort.created event, delivered to your webhook subscriptions.
A replay with the same Idempotency-Key returns the original cohort without a second row or event.

Create a cohort

Create a cohort

Authorization

Request headers

Request body

Example

Response

Response fields

Example response

Agent recipe

Notes

Related

Authorization

Request headers

Request body

Example

Response

Response fields

Example response

Agent recipe

Notes

Related