Schedule a live session

POST /api/v1/live-sessions

Schedules a live session. A live targets a cohort — it is the only target open to writing today — and it cannot start in the past. The provider is detected from the link when it is Zoom or Google Meet.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

Requirement	Rule for this endpoint
Business role	None
Resource scope	Cohort and host belong to the key's organization
Participation	None
Resource state	The cohort is not `completed` or `archived`

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this organization
`Idempotency-Key`	yes	Stable key for this live; a replay returns the first result
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`title`	string	yes	no	3 to 140 characters
`description`	string	no	yes	Up to 2000 characters
`type`	string	yes	no	`masterclass`, `workshop`, `qa`, `group_coaching` or `other`
`startsAt`	string	yes	no	ISO 8601 instant, not in the past
`endsAt`	string	yes	no	ISO 8601 instant, after `startsAt`
`timezone`	string	yes	no	IANA time zone, for example `Europe/Paris`
`accessUrl`	string	yes	no	`https://` meeting link
`provider`	string	no	no	`zoom`, `google_meet` or `other`; the link wins when recognised
`replayUrl`	string	no	yes	`https://` replay link
`hostUserId`	UUID	no	yes	Account of a member of the school
`targetType`	string	yes	no	`cohort`
`targetCohortId`	UUID	yes	no	Cohort of the key's organization

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/live-sessions" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: live-autumn-qa-w1" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Q&A",
    "type": "qa",
    "startsAt": "2026-10-08T17:00:00.000Z",
    "endsAt": "2026-10-08T18:00:00.000Z",
    "timezone": "Europe/Paris",
    "accessUrl": "https://meet.google.com/abc-defg-hij",
    "targetType": "cohort",
    "targetCohortId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b"
  }'

Response

201 Created — the live, scheduled.
200 OK — replayed: true: the key was already used, the original live comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a field out of bounds, a start in the past, an end before the start, a non-https link, a target other than cohort, an unknown cohort, or a host who is not a member of the school.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer is not OWNER or ADMIN, or the cohort is closed.

Response fields

Same fields as one item of List live sessions, without targetCohortName.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "title": "Weekly Q&A",
    "description": null,
    "type": "qa",
    "status": "scheduled",
    "startsAt": "2026-10-08T17:00:00.000Z",
    "endsAt": "2026-10-08T18:00:00.000Z",
    "timezone": "Europe/Paris",
    "accessUrl": "https://meet.google.com/abc-defg-hij",
    "provider": "google_meet",
    "replayUrl": null,
    "hostUserId": null,
    "targetType": "cohort",
    "targetCohortId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "cancelledAt": null,
    "cancellationReason": null,
    "createdAt": "2026-10-01T08:30:00.000Z",
    "updatedAt": "2026-10-01T08:30:00.000Z"
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Notes

No email and no in-app notification are sent today. Scheduling records the live and its audit line; the targeted members see it in their agenda.
A replay with the same Idempotency-Key creates no second live.

Scheduling retry contract

Keep one idempotency key for one normalized intention. Current authorization is checked again on retry. A different payload or resource with that key, or an older key whose intention cannot be verified, returns 409 conflict without another mutation. Inspect the original outcome before creating a new command. Identical retries do not resend notifications.

POST /api/v1/live-sessions

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — `403`

Requirement	Rule for this endpoint
Business role	None
Resource scope	Cohort and host belong to the key's organization
Participation	None
Resource state	The cohort is not `completed` or `archived`

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this organization
`Idempotency-Key`	yes	Stable key for this live; a replay returns the first result
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`title`	string	yes	no	3 to 140 characters
`description`	string	no	yes	Up to 2000 characters
`type`	string	yes	no	`masterclass`, `workshop`, `qa`, `group_coaching` or `other`
`startsAt`	string	yes	no	ISO 8601 instant, not in the past
`endsAt`	string	yes	no	ISO 8601 instant, after `startsAt`
`timezone`	string	yes	no	IANA time zone, for example `Europe/Paris`
`accessUrl`	string	yes	no	`https://` meeting link
`provider`	string	no	no	`zoom`, `google_meet` or `other`; the link wins when recognised
`replayUrl`	string	no	yes	`https://` replay link
`hostUserId`	UUID	no	yes	Account of a member of the school
`targetType`	string	yes	no	`cohort`
`targetCohortId`	UUID	yes	no	Cohort of the key's organization

Example

bash

curl -X POST "$COHORTE_API_BASE_URL/api/v1/live-sessions" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: live-autumn-qa-w1" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Weekly Q&A",
    "type": "qa",
    "startsAt": "2026-10-08T17:00:00.000Z",
    "endsAt": "2026-10-08T18:00:00.000Z",
    "timezone": "Europe/Paris",
    "accessUrl": "https://meet.google.com/abc-defg-hij",
    "targetType": "cohort",
    "targetCohortId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b"
  }'

Response

201 Created — the live, scheduled.
200 OK — replayed: true: the key was already used, the original live comes back.
400 Bad Request — missing Idempotency-Key, invalid JSON, a field out of bounds, a start in the past, an end before the start, a non-https link, a target other than cohort, an unknown cohort, or a host who is not a member of the school.
401 Unauthorized — missing, unknown or expired key.
403 Forbidden — the bearer is not OWNER or ADMIN, or the cohort is closed.

Response fields

Same fields as one item of List live sessions, without targetCohortName.

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "title": "Weekly Q&A",
    "description": null,
    "type": "qa",
    "status": "scheduled",
    "startsAt": "2026-10-08T17:00:00.000Z",
    "endsAt": "2026-10-08T18:00:00.000Z",
    "timezone": "Europe/Paris",
    "accessUrl": "https://meet.google.com/abc-defg-hij",
    "provider": "google_meet",
    "replayUrl": null,
    "hostUserId": null,
    "targetType": "cohort",
    "targetCohortId": "3a1f7c2e-5b6d-4e8f-9a0b-1c2d3e4f5a6b",
    "cancelledAt": null,
    "cancellationReason": null,
    "createdAt": "2026-10-01T08:30:00.000Z",
    "updatedAt": "2026-10-01T08:30:00.000Z"
  },
  "correlationId": "c0ffee00-1111-4222-8333-444455556666"
}

Notes

No email and no in-app notification are sent today. Scheduling records the live and its audit line; the targeted members see it in their agenda.
A replay with the same Idempotency-Key creates no second live.

Schedule a live session

Schedule a live session

Authorization

Request headers

Request body

Example

Response

Response fields

Example response

Notes

Related

Scheduling retry contract

Authorization

Request headers

Request body

Example

Response

Response fields

Example response

Notes

Related

Scheduling retry contract