Read a lesson by its identifier

GET /api/v1/programs/{programId}/lessons/by-external-id/{externalId}

Reads a lesson through your own identifier (externalId, e.g. LIV-04) instead of its UUID. An identifier is unique only inside its program, which is why it is always read under the program path. The comparison ignores case: liv-04 finds LIV-04.

The answer is exactly the one of Read a lesson: same fields, same complete content.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — answered as `404`

Requirement	Rule for this endpoint
Business role	An organization-scoped `program_director`, or the `coach` of this program, reads as well
Resource scope	A lesson of a program of the school attached to the API key
Resource state	Any status — drafts and archived lessons are readable here

Path parameters

Parameter	Type	Required	Description
`programId`	UUID	yes	Program that holds the lesson
`externalId`	string	yes	The lesson's identifier: 1 to 32 letters, digits, `.`, `-`, `_`

Request headers

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

Example

bash

curl "$COHORTE_API_BASE_URL/api/v1/programs/$PROGRAM_ID/lessons/by-external-id/LIV-04" \
  -H "x-api-key: $COHORTE_API_KEY"

Response

200 OK — the lesson and its resources.
400 Bad Request — programId is not a UUID, or externalId is malformed.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
404 Not Found — no lesson of this program carries the identifier, the program belongs to another school, or the bearer cannot read the lesson.

Example response

json

{
  "success": true,
  "data": {
    "id": "5d9f3a60-1c2b-4e7d-8f4a-6b7c8d9e0f1a",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "courseId": null,
    "sectionId": null,
    "title": "Export a deliverable",
    "content": "## The gesture\n…\n\n## Pour ton agent\nRead routes/export.ts first.",
    "videoUrl": null,
    "status": "draft",
    "position": 4,
    "externalId": "LIV-04",
    "audience": ["freelance", "saas"],
    "level": "essential",
    "prerequisites": ["LIV-01"],
    "videoMinutes": 4,
    "taskRef": "T1.1",
    "createdAt": "2026-10-07T09:00:00.000Z",
    "updatedAt": "2026-10-07T09:00:00.000Z",
    "resources": []
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

GET /api/v1/programs/{programId}/lessons/by-external-id/{externalId}

The answer is exactly the one of Read a lesson: same fields, same complete content.

Authorization

Role in the organization	This endpoint
`OWNER`	Allowed
`ADMIN`	Allowed
`MEMBER`	Refused — answered as `404`

Requirement	Rule for this endpoint
Business role	An organization-scoped `program_director`, or the `coach` of this program, reads as well
Resource scope	A lesson of a program of the school attached to the API key
Resource state	Any status — drafts and archived lessons are readable here

Path parameters

Parameter	Type	Required	Description
`programId`	UUID	yes	Program that holds the lesson
`externalId`	string	yes	The lesson's identifier: 1 to 32 letters, digits, `.`, `-`, `_`

Request headers

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

Example

bash

curl "$COHORTE_API_BASE_URL/api/v1/programs/$PROGRAM_ID/lessons/by-external-id/LIV-04" \
  -H "x-api-key: $COHORTE_API_KEY"

Response

200 OK — the lesson and its resources.
400 Bad Request — programId is not a UUID, or externalId is malformed.
401 Unauthorized — the key is missing, invalid, or no longer attached to a member.
404 Not Found — no lesson of this program carries the identifier, the program belongs to another school, or the bearer cannot read the lesson.

Example response

json

{
  "success": true,
  "data": {
    "id": "5d9f3a60-1c2b-4e7d-8f4a-6b7c8d9e0f1a",
    "programId": "9f2c0a1e-4b7d-4c1a-9e3f-2a6b8c0d1e2f",
    "courseId": null,
    "sectionId": null,
    "title": "Export a deliverable",
    "content": "## The gesture\n…\n\n## Pour ton agent\nRead routes/export.ts first.",
    "videoUrl": null,
    "status": "draft",
    "position": 4,
    "externalId": "LIV-04",
    "audience": ["freelance", "saas"],
    "level": "essential",
    "prerequisites": ["LIV-01"],
    "videoMinutes": 4,
    "taskRef": "T1.1",
    "createdAt": "2026-10-07T09:00:00.000Z",
    "updatedAt": "2026-10-07T09:00:00.000Z",
    "resources": []
  },
  "correlationId": "0f6b1d92-5c3e-4a8b-9d71-3e2f4a6b8c10"
}

Read a lesson by its identifier

Read a lesson by its identifier

Authorization

Path parameters

Request headers

Example

Response

Example response

Related

Authorization

Path parameters

Request headers

Example

Response

Example response

Related