PATCH /api/v1/live-sessions/{liveSessionId}
Changes a scheduled live. A field you omit is left alone; a field you send as
null is erased — description, replayUrl, hostUserId.
A cohort live must retain a cohort audience: targetCohortId: null is refused.
Sending a new targetCohortId validates that cohort in your school and its current
state, even when targetType is omitted. Omitting both fields preserves the audience.
The response says whether the change touched what a member acts on — window,
time zone, link, provider, target, host or type (rescheduled) — or only the
title, description or replay (updated). Cancelling is its own command.
| Role in the organization | This endpoint |
|---|
OWNER | Allowed |
ADMIN | Allowed |
MEMBER | Refused — 403 |
| Requirement | Rule for this endpoint |
|---|
| Business role | None |
| Resource scope | The live, its cohort and its host belong to the key's organization |
| Participation | None |
| Resource state | The live is not cancelled; a new target cohort is not closed |
| Parameter | Type | Required | Description |
|---|
liveSessionId | UUID | yes | Live session of the key's organization |
| Header | Required | Description |
|---|
x-api-key | yes | API key created for this organization |
Idempotency-Key | yes | Stable key for this change; a replay returns the first result |
X-Correlation-Id | no | Caller correlation id, returned or generated |
Request body
Every field of Schedule a live session,
all optional. startsAt and endsAt keep the same rules: not in the past, end
after start.
curl -X PATCH "$COHORTE_API_BASE_URL/api/v1/live-sessions/$LIVE_SESSION_ID" \
-H "x-api-key: $COHORTE_API_KEY" \
-H "Idempotency-Key: live-autumn-qa-w1-move" \
-H "Content-Type: application/json" \
-d '{"startsAt": "2026-10-09T17:00:00.000Z", "endsAt": "2026-10-09T18:00:00.000Z"}'
200 OK — the live as updated, with change. replayed: true when the key was already used.400 Bad Request — missing Idempotency-Key, invalid JSON, a field out of bounds, a window in the past or reversed, 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, the live is cancelled, or the new cohort is closed.404 Not Found — the live is unknown or belongs to another school.
Same fields as Schedule a live session, plus:
| Field | Type | Description |
|---|
data.change | string | rescheduled when a structuring field changed, else updated |
{
"success": true,
"replayed": false,
"data": {
"id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"title": "Weekly Q&A",
"description": null,
"type": "qa",
"status": "scheduled",
"startsAt": "2026-10-09T17:00:00.000Z",
"endsAt": "2026-10-09T18: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-02T10:00:00.000Z",
"change": "rescheduled"
},
"correlationId": "c0ffee00-1111-4222-8333-444455556666"
}
- No email and no in-app notification are sent today, even for a reschedule.
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.
