API endpoints

Search

Search for lessons that are related to your search term

5.1 Lesson search by video transcript

GET /search/transcripts

Use when you want to search the spoken content of lesson videos. Returns up to 5 lessons whose transcripts contain similar text, each with a transcript snippet showing the match. No filters; searches every published transcript. Not for: terms in the lesson title (GET /search/lessons); metadata for a known lesson (GET /lessons/{lesson}/summary); a transcript by slug (GET /lessons/{lesson}/transcript). Example queries: the mitochondria are the powerhouse, to be or not to be, carry the one.

Inputs (query)

Name	Type	Description	Example
q	string	A snippet of text to search for in the lesson video transcripts	Who were the romans?

Output (response)

Name	Type	Description
lessonTitle	string	The lesson title
lessonSlug	string	The lesson slug identifier
transcriptSnippet	string	The snippet of the transcript that matched the search term
message	string	The error message
code	string	The error code
issues	array[object]	An array of issues that were responsible for the error
message	string	The error message
code	string	The error code
issues	array[object]	An array of issues that were responsible for the error
message	string	The error message
code	string	The error code
issues	array[object]	An array of issues that were responsible for the error

Sample response

[
  {
    "lessonTitle": "The Roman invasion of Britain ",
    "lessonSlug": "the-roman-invasion-of-britain",
    "transcriptSnippet": "The Romans were ready,"
  },
  {
    "lessonTitle": "The changes to life brought about by Roman settlement",
    "lessonSlug": "the-changes-to-life-brought-about-by-roman-settlement",
    "transcriptSnippet": "when the Romans came."
  },
  {
    "lessonTitle": "Boudica's rebellion against Roman rule",
    "lessonSlug": "boudicas-rebellion-against-roman-rule",
    "transcriptSnippet": "kings who resisted the Romans were,"
  },
  {
    "lessonTitle": "How far religion changed under Roman rule",
    "lessonSlug": "how-far-religion-changed-under-roman-rule",
    "transcriptSnippet": "for the Romans."
  }
]

5.2 Lesson search by title

GET /search/lessons

Use when you want to find lessons whose titles match a search term. Returns up to 20 lessons ranked by title similarity — each with slug, title, URL, similarity score, and the unit(s) the lesson appears in. Optional keyStage, subject, and unit narrow the search. Not for: searching what's said in lesson videos (GET /search/transcripts); metadata for a known lesson (GET /lessons/{lesson}/summary); listing every lesson in a key stage + subject without ranking (GET /key-stages/{keyStage}/subject/{subject}/lessons). Example queries: KS3 science photosynthesis, fractions year 5, Macbeth soliloquy.

Inputs (query)

Name	Type	Description	Example
q	string	Search query text snippet	gothic
keyStage [optional]	string	Key stage slug to filter by, e.g. 'ks2' - note that casing is important here, and should be lowercase	ks2
subject [optional]	string	Subject slug to filter by, e.g. 'english' - note that casing is important here, and should be lowercase	english
unit [optional]	string	Optional unit slug to additionally filter by	Gothic poetry

Output (response)

Name	Type	Description
lessonSlug	string	The lesson slug identifier
lessonTitle	string	The lesson title
oakUrl	string	The Oak National URL for the lesson
similarity	number	The snippet of the transcript that matched the search term
units	array[object]	The units that the lesson is part of. See sample response below
message	string	The error message
code	string	The error code
issues	array[object]	An array of issues that were responsible for the error
message	string	The error message
code	string	The error code
issues	array[object]	An array of issues that were responsible for the error
message	string	The error message
code	string	The error code
issues	array[object]	An array of issues that were responsible for the error

Sample response

[
  {
    "lessonSlug": "performing-your-chosen-gothic-poem",
    "lessonTitle": "Performing your chosen Gothic poem",
    "oakUrl": "https://www.thenational.academy/teachers/lessons/performing-your-chosen-gothic-poem",
    "similarity": 0.20588236,
    "units": [
      {
        "unitSlug": "gothic-poetry",
        "unitTitle": "Gothic poetry",
        "examBoardTitle": null,
        "keyStageSlug": "ks3",
        "subjectSlug": "english"
      }
    ]
  },
  {
    "lessonSlug": "the-twisted-tree-the-novel-as-a-gothic-text",
    "lessonTitle": "'The Twisted Tree': the novel as a Gothic text",
    "oakUrl": "https://www.thenational.academy/teachers/lessons/the-twisted-tree-the-novel-as-a-gothic-text",
    "similarity": 0.19444445,
    "units": [
      {
        "unitSlug": "the-twisted-tree-fiction-reading",
        "unitTitle": "'The Twisted Tree': fiction reading",
        "examBoardTitle": null,
        "keyStageSlug": "ks3",
        "subjectSlug": "english"
      }
    ]
  }
]