API endpoints

Lesson data

We have the following types of data available for each published lesson:

Lesson title
Unit title
Subject
Key stage
Keywords and their pupil-friendly definitions
Key learning points - a summary of the key knowledge taught during the lesson.
Common misconceptions and a suggested response
Pupil lesson outcome - a statement outlining what the pupil will learn during the lesson
Teacher tips
Content guidance - suggested guidance for the pupil or teacher about the
content within the lesson.
Supervision level - to indicate if the content is appropriate for a pupil learning on their own or under the supervision of an adult.
Whether downloadable resources are available
Quiz questions and answers

2.1 Lesson video transcript

GET /lessons/{lesson}/transcript

Use when you have a lesson slug and need the video transcript — for accessibility, captioning, or text analysis. Returns the transcript as an array of sentences plus a raw WebVTT captions file (vtt) suitable for a <track> element. Not for: searching across transcripts (GET /search/transcripts); the video file itself (GET /lessons/{lesson}/assets/{type} with type=video); lesson metadata (GET /lessons/{lesson}/summary).

Inputs (path)

Name	Type	Description	Example
lesson	string	The slug of the lesson	checking-understanding-of-basic-transformations

Output (response)

Name	Type	Description
transcript	string	The transcript for the lesson video
vtt	string	The contents of the .vtt file for the lesson video, which maps captions to video timestamps.
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

{
  "transcript": "Hello, I'm Mrs. Lashley. I'm looking forward to guiding you through your learning today...",
  "vtt": "WEBVTT\n\n1\n00:00:06.300 --> 00:00:08.070\n<v ->Hello, I'm Mrs. Lashley.</v>\n\n2\n00:00:08.070 --> 00:00:09.240\nI'm looking forward to guiding you\n\n3\n00:00:09.240 --> 00:00:10.980\nthrough your learning today..."
}

2.2 Downloadable assets for a lesson

GET /lessons/{lesson}/assets

Use when you have a lesson slug and need the list of what's downloadable. Returns every available asset type with a signed download URL per asset and attribution. The 9 type values are: slideDeck, starterQuiz, starterQuizAnswers, exitQuiz, exitQuizAnswers, worksheet, worksheetAnswers, supplementaryResource, video. Pass type to return only one. Lesson content is under OGL v3.0; assets are either Oak-owned or third-party under an OGL-compatible licence. Attribution required — see https://open-api.thenational.academy/docs/about-oaks-api/terms. Not for: streaming the file itself (GET /lessons/{lesson}/assets/{type}); bulk asset retrieval across a key stage + subject (GET /key-stages/{keyStage}/subject/{subject}/assets), a sequence (GET /sequences/{sequence}/assets), or one programme (GET /sequences/{sequence}/programmes/{programme}/assets); lesson metadata (GET /lessons/{lesson}/summary).

Inputs (path, query)

Name	Type	Description	Example
lesson	string	The lesson slug identifier	child-workers-in-the-victorian-era
type [optional]	string	Use the this type and the lesson slug in conjunction to get a signed download URL to the asset type from the /api/lessons/{slug}/asset/{type} endpoint	slideDeck

Output (response)

Name	Type	Description
oakUrl	string	The Oak National URL for the lesson
attribution	array[string]	Licence information for any third-party content contained in the lessons' downloadable resources
assets	array[object]	List of assets
type	string	Use the this type and the lesson slug in conjunction to get a signed download URL to the asset type from the /api/lessons/{slug}/asset/{type} endpoint
label	string	The label for the asset
url	string	The download endpoint for the asset.
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

{
  "oakUrl": "https://www.thenational.academy/teachers/lessons/using-numerals",
  "attribution": [
    "Copyright XYZ Authors",
    "Creative Commons Attribution Example 4.0"
  ],
  "assets": [
    {
      "label": "Worksheet",
      "type": "worksheet",
      "url": "https://open-api.thenational.academy/api/v0/lessons/using-numerals/assets/worksheet"
    },
    {
      "label": "Worksheet Answers",
      "type": "worksheetAnswers",
      "url": "https://open-api.thenational.academy/api/v0/lessons/using-numerals/assets/worksheetAnswers"
    },
    {
      "label": "Video",
      "type": "video",
      "url": "https://open-api.thenational.academy/api/v0/lessons/using-numerals/assets/video"
    }
  ]
}

2.3 Stream a lesson asset file

GET /lessons/{lesson}/assets/{type}

Use when you want to download one specific asset for a lesson — slide deck, worksheet, etc. Returns the file directly. Call GET /lessons/{lesson}/assets first to see which type values are available. Valid type values: slideDeck, starterQuiz, starterQuizAnswers, exitQuiz, exitQuizAnswers, worksheet, worksheetAnswers, supplementaryResource, video. Lesson content is under OGL v3.0; assets are either Oak-owned or third-party under an OGL-compatible licence. Attribution required — see https://open-api.thenational.academy/docs/about-oaks-api/terms. Not for: listing which asset types a lesson has (GET /lessons/{lesson}/assets); fetching the transcript (GET /lessons/{lesson}/transcript).

Inputs (path)

Name	Type	Description	Example
lesson	string	The lesson slug	child-workers-in-the-victorian-era
type	string	Use the this type and the lesson slug in conjunction to get a signed download URL to the asset type from the /api/lessons/{slug}/asset/{type} endpoint	slideDeck

Output (response)

Name	Type	Description
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

{}

2.4 Lesson summary by slug

GET /lessons/{lesson}/summary

Use when you have a lesson slug and need its full metadata: title, key stage, subject, unit, keywords, key learning points, misconceptions, pupil lesson outcome, teacher tips, content guidance, supervision level, and downloadsAvailable. Returns the lesson summary record. Not for: finding a lesson from a search term (GET /search/lessons); searching what's said in lesson videos (GET /search/transcripts); listing every lesson in a unit or subject (GET /key-stages/{keyStage}/subject/{subject}/lessons); the transcript or assets (GET /lessons/{lesson}/transcript or GET /lessons/{lesson}/assets). Example slug: imagining-you-are-the-characters-the-three-billy-goats-gruff.

Inputs (path)

Name	Type	Description	Example
lesson	string	The slug of the lesson	joining-using-and

Output (response)

Name	Type	Description
lessonTitle	string	The lesson title
canonicalUrl	string	The canonical Oak National URL for the lesson
oakUrl	string	The Oak National URL for the lesson
units	array[object]	All the units (including programme variants) this lesson is part of. Each entry is a unique combination of unit slug and programme factors.
unitSlug	string	The unit slug identifier
unitTitle	string	The unit title
programmeFactors	object	The programme-factor values that identify which variant of the unit this lesson sits in. Omitted when the unit has no programme factors.
examBoard	object	The exam board that identifies this unit variant
slug	string	The slug identifier for the science child subject
title	string	The title of the science child subject
pathway	object	The pathway that identifies this unit variant
tier	object	The tier that identifies this unit variant
childSubject	object	The science child subject that identifies this unit variant
subjectSlug	string	The subject slug identifier
subjectTitle	string	The subject slug identifier
keyStageSlug	string	The key stage slug identifier
keyStageTitle	string	The key stage title
lessonKeywords	array[object]	The lesson's keywords and their descriptions
properties		[object Object]
keyword	string	The keyword
description	string	A definition of the keyword
keyLearningPoints	array[object]	The lesson's key learning points
keyLearningPoint	string	A key learning point
misconceptionsAndCommonMistakes	array[object]	The lesson’s anticipated common misconceptions and suggested teacher responses
misconception	string	A common misconception
response	string	Suggested teacher response to a common misconception
pupilLessonOutcome	string	Suggested teacher response to a common misconception
teacherTips	array[object]	Helpful teaching tips for the lesson
items	object	A teaching tip
contentGuidance	array, null	Full guidance about the types of lesson content for the teacher to consider (where appropriate)
contentGuidanceArea	string	Category of content guidance
supervisionlevel_id	number	The ID of the supervision level for the identified type of content. See ‘What are the types of content guidance?’ for more information.
contentGuidanceLabel	string	Content guidance label
contentGuidanceDescription	string	A detailed description of the type of content that we suggest needs guidance.
supervisionLevel	string, null	The ID of the supervision level for the identified type of content. See ‘What are the types of content guidance?’ for more information.
downloadsAvailable	boolean	Whether the lesson currently has any downloadable assets availableNote: this field reflects the current availability of downloadable assets, which reflects the availability of early-release content available for the hackathon. All lessons will eventually have downloadable assets available.
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": "Using vector tools to draw and modify shapes",
  "canonicalUrl": "https://www.thenational.academy/teachers/lessons/using-vector-tools-to-draw-and-modify-shapes",
  "oakUrl": "https://www.thenational.academy/teachers/lessons/using-vector-tools-to-draw-and-modify-shapes",
  "units": [
    {
      "unitSlug": "developing-vector-graphics",
      "unitTitle": "Developing vector graphics"
    }
  ],
  "subjectSlug": "computing",
  "subjectTitle": "Computing",
  "keyStageSlug": "ks3",
  "keyStageTitle": "Key Stage 3",
  "lessonKeywords": [
    {
      "keyword": "vector graphic",
      "description": "an image made up of lines and shapes"
    },
    {
      "keyword": "z-order",
      "description": "the order of overlapping objects"
    },
    {
      "keyword": "layer",
      "description": "the level on which an object (e.g. text, shapes and photos) can be placed relative to other objects"
    }
  ],
  "keyLearningPoints": [
    {
      "keyLearningPoint": "Vector graphics are made from shapes described by coordinates, not pixels."
    },
    {
      "keyLearningPoint": "Vector illustrations are built using simple shapes."
    },
    {
      "keyLearningPoint": "Vector graphics use z-order to show which shapes are in front and are visible."
    }
  ],
  "misconceptionsAndCommonMistakes": [
    {
      "misconception": "Vector graphics are made from pixels and can lose quality when resized.",
      "response": "Vector graphics are made from lines and shapes. They do not lose quality when resized."
    }
  ],
  "pupilLessonOutcome": "I can use software to draw and modify vector shapes.",
  "teacherTips": [
    {
      "teacherTip": "You need to be familiar with the basic tools and features of vector editing software. The Inkscape tutorials may be useful — oak.link/inkscape-tutorials"
    }
  ],
  "contentGuidance": null,
  "supervisionLevel": null,
  "downloadsAvailable": true
}

2.1 Lesson video transcript
2.2 Downloadable assets for a lesson
2.3 Stream a lesson asset file
2.4 Lesson summary by slug

Lesson data

2.1 Lesson video transcript

GET /lessons/{lesson}/transcript

Inputs (path)

Output (response)

Sample response

2.2 Downloadable assets for a lesson

GET /lessons/{lesson}/assets

Inputs (path, query)

Output (response)

Sample response

2.3 Stream a lesson asset file

GET /lessons/{lesson}/assets/{type}

Inputs (path)

Output (response)

Sample response

2.4 Lesson summary by slug

GET /lessons/{lesson}/summary

Inputs (path)

Output (response)

Sample response

Contents