Get a group

GET /api/v1/groups/{groupId}

Returns one Group with its current and closed membership periods. A foreign Group is indistinguishable from a missing Group.

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 in the Organization attached to the API key
Resource state	Any lifecycle state is readable

Path parameters

Parameter	Type	Required	Description
`groupId`	UUID	yes	Group in the key's Organization

Example

bash

curl "$COHORTE_API_BASE_URL/api/v1/groups/$GROUP_ID" \
  -H "x-api-key: $COHORTE_API_KEY"

Response

200 OK — the Group and membership history.
400 Bad Request — groupId is not a UUID.
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 is unknown or belongs to another Organization.
500 Internal Server Error — the Group could not be read.

Response fields

Field	Type	Nullable	Description
`success`	boolean	no	Always `true` on success
`data.id`	UUID	no	Group identifier
`data.name`	string	no	Group name
`data.type`	string	no	Group type
`data.scope`	string	no	Group scope
`data.programId`	UUID	yes	Scoped Program
`data.programName`	string	yes	Current Program name
`data.cohortId`	UUID	yes	Scoped Cohort
`data.cohortName`	string	yes	Current Cohort name
`data.startsAt`	ISO 8601 string	yes	Optional start instant
`data.endsAt`	ISO 8601 string	yes	Optional end instant
`data.capacity`	integer	yes	Maximum open periods or `null`
`data.activeMembershipCount`	integer	no	Active occupancy in the current window
`data.lifecycle`	string	no	`scheduled`, `active`, or `expired`
`data.memberships[].membershipId`	UUID	no	Membership-period identifier
`data.memberships[].enrollmentId`	UUID	no	Enrollment identifier
`data.memberships[].joinedAt`	ISO 8601 string	no	Period start
`data.memberships[].leftAt`	ISO 8601 string	yes	Period end; `null` while open
`data.memberships[].firstName`	string	no	Person first name
`data.memberships[].lastName`	string	yes	Person last name
`data.memberships[].email`	string	yes	Person email
`data.memberships[].programId`	UUID	no	Enrollment Program
`data.memberships[].programName`	string	no	Enrollment Program name
`data.memberships[].cohortId`	UUID	yes	Enrollment Cohort
`data.memberships[].cohortName`	string	yes	Enrollment Cohort name
`data.memberships[].enrollmentStatus`	string	no	Current Enrollment status
`correlationId`	string	no	Request correlation identifier

Example response

json

{"success":true,"data":{"id":"33333333-3333-4333-8333-333333333333","name":"Advanced","type":"level","scope":"program","programId":"11111111-1111-4111-8111-111111111111","programName":"Expert Track","cohortId":null,"cohortName":null,"startsAt":null,"endsAt":null,"capacity":20,"activeMembershipCount":1,"lifecycle":"active","memberships":[{"membershipId":"44444444-4444-4444-8444-444444444444","enrollmentId":"22222222-2222-4222-8222-222222222222","joinedAt":"2026-09-18T08:00:00.000Z","leftAt":null,"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","programId":"11111111-1111-4111-8111-111111111111","programName":"Expert Track","cohortId":null,"cohortName":null,"enrollmentStatus":"active"}]},"correlationId":"req-42"}

Notes

Closed periods remain visible and are never rewritten by a later re-addition.
This endpoint has no side effect and does not require Idempotency-Key.

GET /api/v1/groups/{groupId}

Returns one Group with its current and closed membership periods. A foreign Group is indistinguishable from a missing Group.

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 in the Organization attached to the API key
Resource state	Any lifecycle state is readable

Path parameters

Parameter	Type	Required	Description
`groupId`	UUID	yes	Group in the key's Organization

Example

bash

curl "$COHORTE_API_BASE_URL/api/v1/groups/$GROUP_ID" \
  -H "x-api-key: $COHORTE_API_KEY"

Response

200 OK — the Group and membership history.
400 Bad Request — groupId is not a UUID.
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 is unknown or belongs to another Organization.
500 Internal Server Error — the Group could not be read.

Response fields

Field	Type	Nullable	Description
`success`	boolean	no	Always `true` on success
`data.id`	UUID	no	Group identifier
`data.name`	string	no	Group name
`data.type`	string	no	Group type
`data.scope`	string	no	Group scope
`data.programId`	UUID	yes	Scoped Program
`data.programName`	string	yes	Current Program name
`data.cohortId`	UUID	yes	Scoped Cohort
`data.cohortName`	string	yes	Current Cohort name
`data.startsAt`	ISO 8601 string	yes	Optional start instant
`data.endsAt`	ISO 8601 string	yes	Optional end instant
`data.capacity`	integer	yes	Maximum open periods or `null`
`data.activeMembershipCount`	integer	no	Active occupancy in the current window
`data.lifecycle`	string	no	`scheduled`, `active`, or `expired`
`data.memberships[].membershipId`	UUID	no	Membership-period identifier
`data.memberships[].enrollmentId`	UUID	no	Enrollment identifier
`data.memberships[].joinedAt`	ISO 8601 string	no	Period start
`data.memberships[].leftAt`	ISO 8601 string	yes	Period end; `null` while open
`data.memberships[].firstName`	string	no	Person first name
`data.memberships[].lastName`	string	yes	Person last name
`data.memberships[].email`	string	yes	Person email
`data.memberships[].programId`	UUID	no	Enrollment Program
`data.memberships[].programName`	string	no	Enrollment Program name
`data.memberships[].cohortId`	UUID	yes	Enrollment Cohort
`data.memberships[].cohortName`	string	yes	Enrollment Cohort name
`data.memberships[].enrollmentStatus`	string	no	Current Enrollment status
`correlationId`	string	no	Request correlation identifier

Example response

json

{"success":true,"data":{"id":"33333333-3333-4333-8333-333333333333","name":"Advanced","type":"level","scope":"program","programId":"11111111-1111-4111-8111-111111111111","programName":"Expert Track","cohortId":null,"cohortName":null,"startsAt":null,"endsAt":null,"capacity":20,"activeMembershipCount":1,"lifecycle":"active","memberships":[{"membershipId":"44444444-4444-4444-8444-444444444444","enrollmentId":"22222222-2222-4222-8222-222222222222","joinedAt":"2026-09-18T08:00:00.000Z","leftAt":null,"firstName":"Ada","lastName":"Lovelace","email":"ada@example.com","programId":"11111111-1111-4111-8111-111111111111","programName":"Expert Track","cohortId":null,"cohortName":null,"enrollmentStatus":"active"}]},"correlationId":"req-42"}

Notes

Closed periods remain visible and are never rewritten by a later re-addition.
This endpoint has no side effect and does not require Idempotency-Key.

Get a group

Get a group

Authorization

Path parameters

Example

Response

Response fields

Example response

Notes

Related

Authorization

Path parameters

Example

Response

Response fields

Example response

Notes

Related