Update a lesson

PATCH /api/v1/lessons/{lessonId}

Changes the content of a lesson. A field you omit is left alone; a field you send as null is erased. That is what lets you fix a title without sending — or destroying — twenty thousand characters of Markdown.

The status does not change here: publishing and archiving are their own commands.

Authorization

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

Requirement	Rule for this endpoint
Business role	None — writing content is the same gesture as composing the structure
Resource scope	Lesson of the school attached to the API key
Resource state	An archived program or course answers `403`

Path parameters

Parameter	Type	Required	Description
`lessonId`	UUID	yes	Lesson visible from the key's school

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this school
`Idempotency-Key`	yes	Stable key for this change
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`title`	string	no	no	3 to 160 characters
`content`	string	no	yes	Markdown, up to 20 000 characters. `null` erases it
`videoUrl`	string	no	yes	A Vimeo, YouTube or Bunny Stream link. `null` removes the video
`externalId`	string	no	yes	Your stable identifier for the lesson, unique inside the program (case-insensitive): 1 to 32 letters, digits, `.`, `-`, `_`, starting with a letter or digit. `null` clears it
`audience`	string[]	no	no	Who the lesson is for: up to 5 of `all`, `freelance`, `employee`, `agency`, `saas`. `all` cannot be combined. `[]` clears it
`level`	string	no	yes	`essential` or `deep_dive`. `null` clears it
`prerequisites`	string[]	no	no	Up to 20 `externalId`s of other lessons of the program (they may not exist yet). Never the lesson's own `externalId`. `[]` clears them
`videoMinutes`	integer	no	yes	Video duration in minutes, 1 to 600. `null` clears it
`taskRef`	string	no	yes	The task this lesson counts for (e.g. `T1.1`), same format as `externalId`. `null` clears it

json

{"content": "## The plan\n\nOpen with the outcome, then the objection."}

Example

bash

curl -X PATCH "$COHORTE_API_BASE_URL/api/v1/lessons/$LESSON_ID" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Structure a discovery call, step by step"}'

Response

200 OK — the lesson, as it now stands.
400 Bad Request — missing Idempotency-Key, invalid JSON, a title outside 3–160 characters, or a video that is not a Vimeo, YouTube or Bunny Stream link.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN, or the program is archived.
404 Not Found — the lesson is unknown or belongs to another school.
409 Conflict — another lesson of the program already uses this externalId (comparison ignores case).

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "5d9f3a60-1c2b-4e7d-8f4a-6b7c8d9e0f1a",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "courseId": "3b8e2d41-7a6c-4f1e-8b25-9c0d1e2f3a4b",
    "sectionId": "c41e7b03-9d2a-4e6f-b1c8-5a6b7c8d9e0f",
    "title": "Structure a discovery call, step by step",
    "content": "## Why it matters\n\nA discovery call decides the rest of the sale.",
    "videoUrl": "https://vimeo.com/912440188",
    "status": "published",
    "position": 1,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-04T17:12:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Notes

The video address is stored canonically (for Vimeo, vimeo.com/{id}): a player URL, a share link and a channel URL describe the same video, and storing them as pasted would make playback depend on how you copied the link.
The change, its audit entry and the lesson.updated event — which carries only the fields that moved — are written in one transaction.

PATCH /api/v1/lessons/{lessonId}

The status does not change here: publishing and archiving are their own commands.

Authorization

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

Requirement	Rule for this endpoint
Business role	None — writing content is the same gesture as composing the structure
Resource scope	Lesson of the school attached to the API key
Resource state	An archived program or course answers `403`

Path parameters

Parameter	Type	Required	Description
`lessonId`	UUID	yes	Lesson visible from the key's school

Request headers

Header	Required	Description
`x-api-key`	yes	API key created for this school
`Idempotency-Key`	yes	Stable key for this change
`X-Correlation-Id`	no	Caller correlation id, returned or generated

Request body

Field	Type	Required	Nullable	Description
`title`	string	no	no	3 to 160 characters
`content`	string	no	yes	Markdown, up to 20 000 characters. `null` erases it
`videoUrl`	string	no	yes	A Vimeo, YouTube or Bunny Stream link. `null` removes the video
`externalId`	string	no	yes	Your stable identifier for the lesson, unique inside the program (case-insensitive): 1 to 32 letters, digits, `.`, `-`, `_`, starting with a letter or digit. `null` clears it
`audience`	string[]	no	no	Who the lesson is for: up to 5 of `all`, `freelance`, `employee`, `agency`, `saas`. `all` cannot be combined. `[]` clears it
`level`	string	no	yes	`essential` or `deep_dive`. `null` clears it
`prerequisites`	string[]	no	no	Up to 20 `externalId`s of other lessons of the program (they may not exist yet). Never the lesson's own `externalId`. `[]` clears them
`videoMinutes`	integer	no	yes	Video duration in minutes, 1 to 600. `null` clears it
`taskRef`	string	no	yes	The task this lesson counts for (e.g. `T1.1`), same format as `externalId`. `null` clears it

json

{"content": "## The plan\n\nOpen with the outcome, then the objection."}

Example

bash

curl -X PATCH "$COHORTE_API_BASE_URL/api/v1/lessons/$LESSON_ID" \
  -H "x-api-key: $COHORTE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Structure a discovery call, step by step"}'

Response

200 OK — the lesson, as it now stands.
400 Bad Request — missing Idempotency-Key, invalid JSON, a title outside 3–160 characters, or a video that is not a Vimeo, YouTube or Bunny Stream link.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
403 Forbidden — the bearer is not OWNER or ADMIN, or the program is archived.
404 Not Found — the lesson is unknown or belongs to another school.
409 Conflict — another lesson of the program already uses this externalId (comparison ignores case).

Example response

json

{
  "success": true,
  "replayed": false,
  "data": {
    "id": "5d9f3a60-1c2b-4e7d-8f4a-6b7c8d9e0f1a",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "courseId": "3b8e2d41-7a6c-4f1e-8b25-9c0d1e2f3a4b",
    "sectionId": "c41e7b03-9d2a-4e6f-b1c8-5a6b7c8d9e0f",
    "title": "Structure a discovery call, step by step",
    "content": "## Why it matters\n\nA discovery call decides the rest of the sale.",
    "videoUrl": "https://vimeo.com/912440188",
    "status": "published",
    "position": 1,
    "createdAt": "2026-09-01T09:00:00.000Z",
    "updatedAt": "2026-09-04T17:12:00.000Z"
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Notes

The video address is stored canonically (for Vimeo, vimeo.com/{id}): a player URL, a share link and a channel URL describe the same video, and storing them as pasted would make playback depend on how you copied the link.
The change, its audit entry and the lesson.updated event — which carries only the fields that moved — are written in one transaction.

Update a lesson

Update a lesson

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Notes

Related

Authorization

Path parameters

Request headers

Request body

Example

Response

Example response

Notes

Related