Managing cohorts

Creating a cohort

A cohort is created with a set of fields plus at least one section.

Required fields

Field	Rules
name	Required. Max 500 characters. Not unique — duplicate names are allowed.
start_date	Required. Format yyyy-mm-dd hh:mm:ss.
end_date	Required. Same format. Must be after start_date and not in the past.
time_zone	Required. Must be a valid IANA zone (e.g. Europe/Warsaw). Dates are interpreted in this zone and stored as UTC.
status	Required. Either active or inactive. There is no default — omitting it is a validation error.
sections	Required. At least one section, each with a title and at least one card.

Optional fields

Field	Rules
description	Max 3500 characters.
mandatory	Boolean, defaults to false. Immutable after creation — it cannot be changed by any later update.

Read-only / not settable via the API

• public — always returned in responses, but cannot be set on create or update. Currently always false.
• authors — not set at creation; managed through the dedicated author operations. The caller automatically becomes the creator.

Validation errors are returned together as a validation_failed (422) response with a details array, one entry per offending field (e.g. name_required, status_invalid, end_date_in_the_past).

Updating a cohort

Updates are partial (PATCH semantics): only the fields you send change; everything else keeps its current value. Updatable fields are name, description, start_date, end_date, time_zone, status. (mandatory and sections are not accepted on update.)

Time-based rules tighten as a cohort progresses:

• Expired cohorts cannot be modified at all → 409 (cohort_expired_modification_not_allowed). A cohort is expired once its end_date is in the past.
• Once learning has started (any learner has begun), start_date and time_zone become immutable, and end_date can only be extended, never shortened.
• end_date must always stay after start_date and cannot be moved into the past.

TIP

"Learning has started" means at least one member has an activity record in a started, completed, completed-elsewhere, or overdue state.

Deleting a cohort

A cohort is deletable only when all of these hold:

• status is inactive, and
• no learner has started, completed, completed elsewhere, or gone overdue, and
• no learner is in a "never started" state.

If any condition fails, the delete is rejected with 409 (cohort_not_deletable) — "Only inactive cohorts without active learners can be deleted." Deleting a valid cohort also cleans up its sections, members, invitations, progress records, and discussion posts.