Assign programs to a cohort
const url = 'https://api.retorio.com/be/v2/cohorts/b2d7e4a1_55c3_4f28_9e10_7a3d6c4b8f02/programs';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"startDate":"2026-12-01T00:00:00.000Z","endDate":"2027-03-31T23:59:59.000Z","programExtIds":["3c9a7e15_8d42_4b6f_a1e0_5f2d9c8b7a64"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.retorio.com/be/v2/cohorts/b2d7e4a1_55c3_4f28_9e10_7a3d6c4b8f02/programs \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "startDate": "2026-12-01T00:00:00.000Z", "endDate": "2027-03-31T23:59:59.000Z", "programExtIds": [ "3c9a7e15_8d42_4b6f_a1e0_5f2d9c8b7a64" ] }'Assigns one or more programs to this cohort for the given window. Fails the whole call if any of the programs already holds a live assignment in this cohort.
Authentication
Section titled “Authentication”- Auth
- Access key
- Roles
- Owner / Admin / Custom
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Example
b2d7e4a1_55c3_4f28_9e10_7a3d6c4b8f02Request Bodyrequired
Section titled “Request Bodyrequired”object
When every assigned program becomes visible to the cohort.
Example
2026-12-01T00:00:00.000ZWhen the assigned programs stop accepting new attempts. A coaching user keeps seeing an ended assignment they have attempts in. Omit or send null for no end date.
Example
2027-03-31T23:59:59.000ZPrograms to assign, by ext id. A program already holding a live assignment in this cohort fails the whole call. Unassign it first to re-assign with a new period.
Example
[ "3c9a7e15_8d42_4b6f_a1e0_5f2d9c8b7a64"]Responses
Section titled “Responses”Created
object
The assigned program’s ext id.
The assigned program’s title.
object
upcoming before startDate, finished once endDate has passed (never for an open-ended assignment, which has no endDate), active otherwise.
Example
[ { "cohortProgramStatus": "upcoming" }]The request body is not valid, a date is not a valid ISO date, startDate is not before endDate, or a program already holds a live assignment in this cohort. Also answered when the request body is not valid JSON.
object
Canonical error name, e.g. INVALID_ARGUMENT.
object
The HTTP reason phrase, e.g. Bad Request.
Example generated
{ "message": "example", "status": "example", "details": "example"}Not authenticated: the bearer token is missing, malformed, expired or revoked, its sign-in method does not match your organization’s configuration, the user it belongs to was removed, or your organization is deactivated.
object
Canonical error name, e.g. INVALID_ARGUMENT.
Example generated
{ "message": "example", "status": "example", "details": "example"}Refused: the token does not belong to an admin, or your organization does not have the coaching product, or the admin’s roles do not grant cohorts:manage.
object
Canonical error name, e.g. INVALID_ARGUMENT.
object
object
The HTTP reason phrase, e.g. Bad Request.
Example generated
{ "message": "example", "status": "example", "details": "example"}No cohort with this id in your organization, or a program in programExtIds does not exist in it.
object
Canonical error name, e.g. INVALID_ARGUMENT.
Example generated
{ "message": "example", "status": "example", "details": "example"}The request body is larger than 10 MB.
object
The HTTP reason phrase, e.g. Bad Request.
Example generated
{ "statusCode": 1, "message": "example", "error": "example"}The Content-Type charset or the Content-Encoding is one the API cannot decode. Send UTF-8 JSON without a content encoding.
object
The HTTP reason phrase, e.g. Bad Request.
Example generated
{ "statusCode": 1, "message": "example", "error": "example"}Internal Server Error
object
Example generated
{ "additionalProperty": "example"}Retorio is GDPR and DSGVO compliant, EU AI Act aligned, ISO 27001 certified, and hosted on Google Cloud with EU data residency. For anything specific to your rollout, ask your Retorio contact.