Move a cohort to another phase

POST /api/v1/cohorts/{cohortId}/phase

Makes another configured phase the current one, immediately. The move can go forward or backward; there is no scheduled move. The phase position is independent from the computed week of the cohort, and the reason is kept with the transition.

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 cohort belongs to the key's organization
Participation	None
Resource state	The cohort is not closed; the target phase is not already current

Path parameters

Parameter	Type	Required	Description
`cohortId`	UUID	yes	Cohort of the key's organization

Request headers

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

Request body

Field	Type	Required	Nullable	Description
`toPhaseId`	UUID	yes	no	A phase configured on this cohort
`reason`	string	yes	no	1 to 500 characters, trimmed

json

{
  "toPhaseId": "22222222-2222-4222-8222-222222222222",
  "reason": "The group completed the foundations review."
}

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/cohorts/$COHORT_ID/phase" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: cohort-autumn-phase-2" \
  -H "Content-Type: application/json" \
  -d '{"toPhaseId":"22222222-2222-4222-8222-222222222222","reason":"The group completed the foundations review."}'

Response

200 OK — the phase that is now current. replayed: true when the key was already used.
400 Bad Request — missing Idempotency-Key, invalid JSON, toPhaseId that is not a UUID, or a missing or too long reason; code is invalid_request.
401 Unauthorized — missing, unknown or expired key; code is unauthorized.
403 Forbidden — the bearer is not OWNER or ADMIN; code is forbidden.
404 Not Found — the cohort is unknown or belongs to another organization, or toPhaseId is not a phase of this cohort; code is not_found.
409 Conflict — the cohort is closed, or toPhaseId is already the current phase; code is conflict.
500 Internal Server Error — unexpected failure; code is internal_error.

Response fields

Field	Type	Nullable	Description
`success`	boolean	no	`true` for a successful request
`replayed`	boolean	no	`true` when the idempotency key replayed a move
`data.cohortId`	UUID	no	Cohort
`data.phase.id`	UUID	no	Phase that is now current
`data.phase.name`	string	no	Its name
`data.phase.position`	integer	no	Its position in the ordered phase list
`correlationId`	UUID	no	Correlation id for support

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "cohortId": "3a1f5c2e-0000-4000-8000-000000000000",
    "phase": {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Practice",
      "position": 2
    }
  },
  "correlationId": "8c4d2b90-0000-4000-8000-000000000000"
}

Notes

Read the current phase before moving: targeting the phase that is already current is refused.
Replaying the same Idempotency-Key returns the original result and does not append a second transition.
The move writes an audit entry and a domain event with the reason.

POST /api/v1/cohorts/{cohortId}/phase

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 cohort belongs to the key's organization
Participation	None
Resource state	The cohort is not closed; the target phase is not already current

Path parameters

Parameter	Type	Required	Description
`cohortId`	UUID	yes	Cohort of the key's organization

Request headers

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

Request body

Field	Type	Required	Nullable	Description
`toPhaseId`	UUID	yes	no	A phase configured on this cohort
`reason`	string	yes	no	1 to 500 characters, trimmed

json

{
  "toPhaseId": "22222222-2222-4222-8222-222222222222",
  "reason": "The group completed the foundations review."
}

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/cohorts/$COHORT_ID/phase" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: cohort-autumn-phase-2" \
  -H "Content-Type: application/json" \
  -d '{"toPhaseId":"22222222-2222-4222-8222-222222222222","reason":"The group completed the foundations review."}'

Response

200 OK — the phase that is now current. replayed: true when the key was already used.
400 Bad Request — missing Idempotency-Key, invalid JSON, toPhaseId that is not a UUID, or a missing or too long reason; code is invalid_request.
401 Unauthorized — missing, unknown or expired key; code is unauthorized.
403 Forbidden — the bearer is not OWNER or ADMIN; code is forbidden.
404 Not Found — the cohort is unknown or belongs to another organization, or toPhaseId is not a phase of this cohort; code is not_found.
409 Conflict — the cohort is closed, or toPhaseId is already the current phase; code is conflict.
500 Internal Server Error — unexpected failure; code is internal_error.

Response fields

Field	Type	Nullable	Description
`success`	boolean	no	`true` for a successful request
`replayed`	boolean	no	`true` when the idempotency key replayed a move
`data.cohortId`	UUID	no	Cohort
`data.phase.id`	UUID	no	Phase that is now current
`data.phase.name`	string	no	Its name
`data.phase.position`	integer	no	Its position in the ordered phase list
`correlationId`	UUID	no	Correlation id for support

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "cohortId": "3a1f5c2e-0000-4000-8000-000000000000",
    "phase": {
      "id": "22222222-2222-4222-8222-222222222222",
      "name": "Practice",
      "position": 2
    }
  },
  "correlationId": "8c4d2b90-0000-4000-8000-000000000000"
}

Notes

Read the current phase before moving: targeting the phase that is already current is refused.
Replaying the same Idempotency-Key returns the original result and does not append a second transition.
The move writes an audit entry and a domain event with the reason.

Move a cohort to another phase

Move a cohort to another phase

Authorization

Path parameters

Request headers

Request body

Example

Response

Response fields

Example response

Notes

Related

Authorization

Path parameters

Request headers

Request body

Example

Response

Response fields

Example response

Notes

Related