List groups

GET /api/v1/groups

Lists the operational groups in the Organization attached to the API key. The collection contains occupancy summaries, never member names or email addresses.

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

Query parameters

Parameter	Type	Required	Description
`search`	string	no	Case-insensitive name search, up to 100 characters
`type`	string	no	`level`, `specialty`, or `accountability`
`scope`	string	no	`organization`, `program`, or `cohort`
`status`	string	no	Derived lifecycle: `scheduled`, `active`, or `expired`
`programId`	UUID	no	Only groups attached to this Program
`cohortId`	UUID	no	Only groups attached to this Cohort

Example

bash

curl "$COHORTE_API_BASE_URL/api/v1/groups?status=active&type=level" \
  -H "x-api-key: $COHORTE_API_KEY"

Response

200 OK — matching Group summaries.
400 Bad Request — an enum, UUID or search value is invalid.
401 Unauthorized — the API key is invalid or no longer attached to a member.
403 Forbidden — the bearer is not an allowed operator.
500 Internal Server Error — the list 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	`level`, `specialty`, or `accountability`
`data[].scope`	string	no	`organization`, `program`, or `cohort`
`data[].programId`	UUID	yes	Target Program when scoped below Organization
`data[].programName`	string	yes	Current Program name
`data[].cohortId`	UUID	yes	Target Cohort for cohort scope
`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; `null` means unlimited
`data[].activeMembershipCount`	integer	no	Active occupancy; zero before start and after expiry
`data[].lifecycle`	string	no	`scheduled`, `active`, or `expired`
`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":8,"lifecycle":"active"}],"correlationId":"req-42"}

Notes

Scheduled membership periods reserve capacity even though active occupancy is zero.
Read one Group to obtain its membership history.
This endpoint has no side effect and does not require Idempotency-Key.

GET /api/v1/groups

Lists the operational groups in the Organization attached to the API key. The collection contains occupancy summaries, never member names or email addresses.

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

Query parameters

Parameter	Type	Required	Description
`search`	string	no	Case-insensitive name search, up to 100 characters
`type`	string	no	`level`, `specialty`, or `accountability`
`scope`	string	no	`organization`, `program`, or `cohort`
`status`	string	no	Derived lifecycle: `scheduled`, `active`, or `expired`
`programId`	UUID	no	Only groups attached to this Program
`cohortId`	UUID	no	Only groups attached to this Cohort

Example

bash

curl "$COHORTE_API_BASE_URL/api/v1/groups?status=active&type=level" \
  -H "x-api-key: $COHORTE_API_KEY"

Response

200 OK — matching Group summaries.
400 Bad Request — an enum, UUID or search value is invalid.
401 Unauthorized — the API key is invalid or no longer attached to a member.
403 Forbidden — the bearer is not an allowed operator.
500 Internal Server Error — the list 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	`level`, `specialty`, or `accountability`
`data[].scope`	string	no	`organization`, `program`, or `cohort`
`data[].programId`	UUID	yes	Target Program when scoped below Organization
`data[].programName`	string	yes	Current Program name
`data[].cohortId`	UUID	yes	Target Cohort for cohort scope
`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; `null` means unlimited
`data[].activeMembershipCount`	integer	no	Active occupancy; zero before start and after expiry
`data[].lifecycle`	string	no	`scheduled`, `active`, or `expired`
`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":8,"lifecycle":"active"}],"correlationId":"req-42"}

Notes

Scheduled membership periods reserve capacity even though active occupancy is zero.
Read one Group to obtain its membership history.
This endpoint has no side effect and does not require Idempotency-Key.

List groups

List groups

Authorization

Query parameters

Example

Response

Response fields

Example response

Notes

Related

Authorization

Query parameters

Example

Response

Response fields

Example response

Notes

Related