Remove a Group membership

DELETE /api/v1/groups/{groupId}/memberships/{enrollmentId}

Closes the active membership period. It does not delete history and changes neither the Enrollment's Program, Cohort nor Path.

Authorization

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

Requirement	Rule for this endpoint
Business role	An organization-scoped `program_director` assignment is required for `MEMBER`
Resource scope	Group and active period in the Organization attached to the API key
Resource state	Expired Groups are read-only

Path parameters

Parameter	Type	Required	Description
`groupId`	UUID	yes	Group in the key's Organization
`enrollmentId`	UUID	yes	Enrollment whose active period must close

Request headers

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

Example

bash

curl -X DELETE "$COHORTE_API_BASE_URL/api/v1/groups/$GROUP_ID/memberships/$ENROLLMENT_ID" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: remove-group-member-$ENROLLMENT_ID"

Response

200 OK — the period was closed or the same command was replayed.
400 Bad Request — a path UUID is invalid or the Group is expired.
401 Unauthorized — the API key is invalid or no longer attached to a member.
403 Forbidden — the bearer is not an allowed operator.
404 Not Found — the Group or active membership is absent or belongs to another Organization.
500 Internal Server Error — the period could not be closed.

Response fields

Field	Type	Nullable	Description
`success`	boolean	no	Always `true` on success
`replayed`	boolean	no	`true` when the same command already completed
`data.id`	UUID	no	Closed membership-period identifier
`data.groupId`	UUID	no	Group identifier
`data.enrollmentId`	UUID	no	Enrollment identifier
`data.leftAt`	ISO 8601 string	yes	Closure instant
`correlationId`	string	no	Request correlation identifier

Example response

json

{"success":true,"replayed":false,"data":{"id":"44444444-4444-4444-8444-444444444444","groupId":"33333333-3333-4333-8333-333333333333","enrollmentId":"22222222-2222-4222-8222-222222222222","leftAt":"2026-09-18T10:00:00.000Z"},"correlationId":"req-42"}

Notes

The period, audit entry and group.member_removed event are updated atomically.
Re-adding the Enrollment later creates a new period; the closed period remains readable.
No request body, email or notification is involved.

DELETE /api/v1/groups/{groupId}/memberships/{enrollmentId}

Closes the active membership period. It does not delete history and changes neither the Enrollment's Program, Cohort nor Path.

Authorization

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

Requirement	Rule for this endpoint
Business role	An organization-scoped `program_director` assignment is required for `MEMBER`
Resource scope	Group and active period in the Organization attached to the API key
Resource state	Expired Groups are read-only

Path parameters

Parameter	Type	Required	Description
`groupId`	UUID	yes	Group in the key's Organization
`enrollmentId`	UUID	yes	Enrollment whose active period must close

Request headers

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

Example

bash

curl -X DELETE "$COHORTE_API_BASE_URL/api/v1/groups/$GROUP_ID/memberships/$ENROLLMENT_ID" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: remove-group-member-$ENROLLMENT_ID"

Response

200 OK — the period was closed or the same command was replayed.
400 Bad Request — a path UUID is invalid or the Group is expired.
401 Unauthorized — the API key is invalid or no longer attached to a member.
403 Forbidden — the bearer is not an allowed operator.
404 Not Found — the Group or active membership is absent or belongs to another Organization.
500 Internal Server Error — the period could not be closed.

Response fields

Field	Type	Nullable	Description
`success`	boolean	no	Always `true` on success
`replayed`	boolean	no	`true` when the same command already completed
`data.id`	UUID	no	Closed membership-period identifier
`data.groupId`	UUID	no	Group identifier
`data.enrollmentId`	UUID	no	Enrollment identifier
`data.leftAt`	ISO 8601 string	yes	Closure instant
`correlationId`	string	no	Request correlation identifier

Example response

json

{"success":true,"replayed":false,"data":{"id":"44444444-4444-4444-8444-444444444444","groupId":"33333333-3333-4333-8333-333333333333","enrollmentId":"22222222-2222-4222-8222-222222222222","leftAt":"2026-09-18T10:00:00.000Z"},"correlationId":"req-42"}

Notes

The period, audit entry and group.member_removed event are updated atomically.
Re-adding the Enrollment later creates a new period; the closed period remains readable.
No request body, email or notification is involved.

Remove a Group membership

Remove a Group membership

Authorization

Path parameters

Request headers

Example

Response

Response fields

Example response

Notes

Related

Authorization

Path parameters

Request headers

Example

Response

Response fields

Example response

Notes

Related