Lessons

A lesson is an authored training unit. Lessons are distinct from raw source content: a lesson teaches a sequence of content pieces. To read the source files themselves, use content.

List lessons

GET /v1/lessons

Lists lessons in the catalog, most recent first, scoped to your lesson visibility (team, public, or managed). Needs the lesson.read permission; an external account does not have it and gets 403.

Query parameters

Parameter	Type	Notes
query	string	Text to find in the lesson title, case-insensitively.
tags	string	Comma-separated tag names, from /v1/tags. A lesson must carry every one. A name that is not a valid tag is a 400.
teamId	string	Lessons shared to this team. It has to be a team in your organization and, unless you can read the whole organization, one you are on; otherwise it is a 400.
cursor	string	Pagination cursor from a previous response.
limit	number	1–100. Default 50.

Request

curl "https://api.mereon.ai/v1/lessons?query=onboarding" \
  -H "Authorization: Bearer $MEREON_TOKEN"

Response

{
  "data": [
    {
      "id": "lsn_6e3f...",
      "title": "New hire onboarding",
      "description": "What every new employee needs in week one.",
      "format": "GUIDED",
      "difficulty": "beginner",
      "status": "OPEN",
      "thoroughness": "STANDARD",
      "simulationsEnabled": true,
      "closedByRetirement": false,
      "sharing": {
        "everyone": false,
        "teams": [{ "id": "tea_77aa...", "name": "Night shift" }]
      },
      "tags": ["onboarding"],
      "stats": null,
      "url": "https://mereon.ai/lessons/new-hire-onboarding",
      "createdAt": "2026-02-01T10:00:00.000Z",
      "updatedAt": "2026-05-20T10:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Field	Type	Notes
format	string	GUIDED (AI-taught) or CURATED (author’s content in order).
difficulty	string	Difficulty level of the lesson.
thoroughness	string	How thorough the AI teaching is: MINIMAL, STANDARD, THOROUGH, or INTENSIVE.
simulationsEnabled	boolean	Whether role-play and other simulations are on for the lesson.
closedByRetirement	boolean	true when the lesson was closed because the topic it taught was retired, rather than closed directly. The list returns open lessons, so it matters on the detail read.
sharing	object	everyone says whether the whole organization can take it, and teams lists the teams it is shared with. Someone who can read the whole organization sees every team. Anyone else sees only the teams they are on, so a lesson shared with another team does not name it.
tags	string[]	The organization’s tags on the lesson, by name.
stats	object | null	enrollmentCount, inProgressCount and completedCount. Shown only to someone who may manage the lesson, and null for everyone else. In the list that means someone who manages lessons across the organization; a team admin sees it on the lesson’s detail read. The counts include people who have since left and people who enrolled themselves.

Get a lesson

GET /v1/lessons/{id}

Lesson detail, including the source content pieces it teaches, in order. Returns 404 if the lesson is not visible to you. A lesson made for one learner, or from a performance review, is not in the catalog and is not found here, even by the person it was made for.

A lesson that has been withdrawn is still returned, with status CLOSED, so an id you stored can be checked.

Response

{
  "id": "lsn_6e3f...",
  "title": "New hire onboarding",
  "description": "What every new employee needs in week one.",
  "format": "GUIDED",
  "difficulty": "beginner",
  "status": "OPEN",
  "thoroughness": "STANDARD",
  "simulationsEnabled": true,
  "closedByRetirement": false,
  "sharing": { "everyone": true, "teams": [] },
  "tags": ["onboarding"],
  "stats": { "enrollmentCount": 42, "inProgressCount": 9, "completedCount": 33 },
  "url": "https://mereon.ai/lessons/new-hire-onboarding",
  "createdAt": "2026-02-01T10:00:00.000Z",
  "updatedAt": "2026-05-20T10:00:00.000Z",
  "contents": [
    { "id": "cnt_44de...", "title": "Finance Handbook", "type": "document", "sequence": 0, "requireWatch": false },
    { "id": "cnt_91ab...", "title": "Office tour", "type": "video", "sequence": 1, "requireWatch": true }
  ]
}

Note

contents lists the source pieces in author or sequence order, limited to the ones you can read. A lesson can be visible to someone who cannot read one of its sources, and naming it would tell them it exists. requireWatch says whether a learner must finish the piece before moving on, in a curated lesson. Resolve each with /v1/content/{id} for metadata or /v1/content/{id}/text for the full text.

List the topics a lesson covers

GET /v1/lessons/{id}/topics

The topics a lesson covers, in the order it teaches them. Only live topics you can read are listed, so a lesson that was closed because its topic was retired covers nothing. A withdrawn lesson can still be asked about by its id. Each topic is a name and a link; read the items under it with /v1/topics/{id}/items. Not paginated.

{
  "data": [
    {
      "id": "top_9f2a...",
      "name": "Expense approval",
      "slug": "expense-approval",
      "sequence": 0,
      "origin": "EXPLICIT",
      "url": "https://mereon.ai/topics/expense-approval"
    }
  ]
}

origin is EXPLICIT when the author picked the topic and DERIVED when it follows from the resources they picked.

Get a lesson’s retraining policy

GET /v1/lessons/{id}/retraining-policy

How often people who finished the lesson are asked to take it again. Needs the lesson-enrollment.read permission, and the lesson has to be one you can see; anything else is a 404. A withdrawn lesson can still be asked about by its id.

{ "policy": { "type": "recurring", "intervalDays": 365, "completionMode": "changed_material" } }

Field	Type	Notes
policy	object | null	null when no policy was set on the lesson. That is not the same as no retraining: the organization’s default applies, and a company role’s curriculum can override either. Company roles reports that override as the item’s retrainingOverride.
policy.type	string	none is an explicit decision not to retrain. recurring repeats every intervalDays.
policy.completionMode	string | null	full_retake means taking the whole lesson again; changed_material means a short lesson on what changed.