API endpoints

Quiz questions

Every lesson has a starter quiz, which tests pupils on the prior knowledge they will need for the lesson, and an exit quiz, which tests pupils' understanding of the lesson content. Each quiz has six questions. Quiz questions can be multiple-choice, ordering, or matching.

4.1 Quiz questions for a lesson

GET /lessons/{lesson}/quiz

Use when you have a lesson slug and need its starter and exit quiz questions with correct answers marked. Returns two arrays, starterQuiz and exitQuiz; each question includes the prompt, the answers (with correct ones flagged), and which answers are distractors. Not for: quiz questions across a sequence (GET /sequences/{sequence}/questions); quiz questions in one programme (GET /sequences/{sequence}/programmes/{programme}/questions); across a key stage + subject (GET /key-stages/{keyStage}/subject/{subject}/questions); lesson metadata or assets (GET /lessons/{lesson}/summary or GET /lessons/{lesson}/assets).

Inputs (path, query)

Name	Type	Description	Example
lesson	string	The lesson slug identifier	imagining-you-are-the-characters-the-three-billy-goats-gruff
filter [optional]	string	Optional filter for question results. Use `images` to return only questions with a question image or image answer.

Output (response)

Name	Type	Description
0	object	Multiple choice answer allows for one or more than one answer to be correct as defined by the distractor field being set to false
1	object	Short answers allow students to enter a free text answer, and the answers array contains a list of acceptable answers
2	object	The student is offered a list from the `match_option` field in the answers array, and must correctly match them to the `correct_choice` value
3	object	The student is offered a list of items to order, and must correctly order them according to the `order` field. When presenting the answer options to the student, you should randomise the order of the items
starterQuiz	array[object]	The starter quiz questions - which test prior knowledge
question	string	The question text
text	string	Supplementary text for the image, if any
type	string	The format of the quiz answer Note: currently, we are only returning text-based quiz answers. In the future, we will also have image-based questions available.
content	string	Quiz question answer
distractor	boolean	Whether the multiple choice question response is the correct answer (false) or is a distractor (true)
matchOption	object	Matching options (LHS)
correctChoice	object	Matching options (RHS), indicating the correct choice
order	number	Indicates the correct ordering of the response
exitQuiz	array[object]	The exit quiz questions - which test on the knowledge learned in the lesson
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

{
  "starterQuiz": [
    {
      "question": "Tick the sentence with the correct punctuation.",
      "questionType": "multiple-choice",
      "answers": [
        {
          "distractor": true,
          "type": "text",
          "content": "the baby cried"
        },
        {
          "distractor": true,
          "type": "text",
          "content": "The baby cried"
        },
        {
          "distractor": false,
          "type": "text",
          "content": "The baby cried."
        },
        {
          "distractor": true,
          "type": "text",
          "content": "the baby cried."
        }
      ]
    }
  ],
  "exitQuiz": [
    {
      "question": "Which word is a verb?",
      "questionType": "multiple-choice",
      "answers": [
        {
          "distractor": true,
          "type": "text",
          "content": "shops"
        },
        {
          "distractor": true,
          "type": "text",
          "content": "Jun"
        },
        {
          "distractor": true,
          "type": "text",
          "content": "I"
        },
        {
          "distractor": false,
          "type": "text",
          "content": "shout"
        }
      ]
    }
  ]
}

4.2 Quiz questions across a sequence

GET /sequences/{sequence}/questions

Use when you want every quiz question across a whole sequence — all programmes combined. Returns questions grouped by lesson in unit sequence order. Pass year as an optional filter to return only that year's questions. Supports offset and limit; Link: rel="next" header signals more pages. Not for: questions in a single programme (GET /sequences/{sequence}/programmes/{programme}/questions); a single lesson's quiz (GET /lessons/{lesson}/quiz); questions for a key stage + subject without programme structure (GET /key-stages/{keyStage}/subject/{subject}/questions).

Inputs (path, query)

Name	Type	Description	Example
sequence	string	The sequence slug identifier, including the key stage 4 option where relevant.	english-primary
year [optional]	number	The year group to filter by. For the physical-education-primary sequence, a value of all-years can also be used.	3
offset [optional]	number	If limiting results returned, this allows you to return the next set of results, starting at the given offset point	50
limit [optional]	number	Limit the number of lessons, e.g. return a maximum of 100 lessons	10
filter [optional]	string	Optional filter for question results. Use `images` to return only questions with a question image or image answer.

Output (response)

Name	Type	Description
0	object	Multiple choice answer allows for one or more than one answer to be correct as defined by the distractor field being set to false
1	object	Short answers allow students to enter a free text answer, and the answers array contains a list of acceptable answers
2	object	The student is offered a list from the `match_option` field in the answers array, and must correctly match them to the `correct_choice` value
3	object	The student is offered a list of items to order, and must correctly order them according to the `order` field. When presenting the answer options to the student, you should randomise the order of the items
lessonSlug	string	The lesson slug identifier
lessonTitle	string	The title of the lesson
starterQuiz	array[object]	The starter quiz questions - which test prior knowledge
question	string	The question text
text	string	Supplementary text for the image, if any
type	string	The format of the quiz answer Note: currently, we are only returning text-based quiz answers. In the future, we will also have image-based questions available.
content	string	Quiz question answer
distractor	boolean	Whether the multiple choice question response is the correct answer (false) or is a distractor (true)
matchOption	object	Matching options (LHS)
correctChoice	object	Matching options (RHS), indicating the correct choice
order	number	Indicates the correct ordering of the response
exitQuiz	array[object]	The exit quiz questions - which test on the knowledge learned in the lesson
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": "3D shapes can be composed from 2D nets",
    "lessonSlug": "3d-shapes-can-be-composed-from-2d-nets",
    "starterQuiz": [
      {
        "question": "Select all of the names of shapes that are polygons.",
        "questionType": "multiple-choice",
        "answers": [
          {
            "type": "text",
            "content": "Cube ",
            "distractor": true
          },
          {
            "type": "text",
            "content": " Square",
            "distractor": false
          },
          {
            "type": "text",
            "content": "Triangle",
            "distractor": false
          },
          {
            "type": "text",
            "content": "Semi-circle",
            "distractor": true
          }
        ]
      }
    ],
    "exitQuiz": [
      {
        "question": "What is a net?",
        "questionType": "multiple-choice",
        "answers": [
          {
            "type": "text",
            "content": "A 3D shape made of 2D shapes folded together. ",
            "distractor": false
          },
          {
            "type": "text",
            "content": "A 2D shape made of 3D shapes folded togehther.",
            "distractor": true
          },
          {
            "type": "text",
            "content": "A type of cube.",
            "distractor": true
          }
        ]
      }
    ]
  }
]

4.3 Quiz questions by key stage and subject

GET /key-stages/{keyStage}/subject/{subject}/questions

Use when you want every quiz question for a key stage + subject, without programme structure or unit sequence order. Returns lessons each with starter and exit quiz questions and answers. Supports offset/limit pagination; Link: rel="next" header signals more pages. Not for: a single lesson's quiz (GET /lessons/{lesson}/quiz); questions across a sequence (GET /sequences/{sequence}/questions); questions in one programme (GET /sequences/{sequence}/programmes/{programme}/questions).

Inputs (path, query)

Name	Type	Description	Example
keyStage	string	Key stage slug to filter by, e.g. 'ks2' - note that casing is important here, and should be lowercase	ks1
subject	string	Subject slug to search by, e.g. 'science' - note that casing is important here	art
offset [optional]	number	If limiting results returned, this allows you to return the next set of results, starting at the given offset point	50
limit [optional]	number	Limit the number of lessons, e.g. return a maximum of 100 lessons	10
filter [optional]	string	Optional filter for question results. Use `images` to return only questions with a question image or image answer.

Output (response)

Name	Type	Description
0	object	Multiple choice answer allows for one or more than one answer to be correct as defined by the distractor field being set to false
1	object	Short answers allow students to enter a free text answer, and the answers array contains a list of acceptable answers
2	object	The student is offered a list from the `match_option` field in the answers array, and must correctly match them to the `correct_choice` value
3	object	The student is offered a list of items to order, and must correctly order them according to the `order` field. When presenting the answer options to the student, you should randomise the order of the items
lessonSlug	string	The lesson slug identifier
lessonTitle	string	The title of the lesson
starterQuiz	array[object]	The starter quiz questions - which test prior knowledge
question	string	The question text
text	string	Supplementary text for the image, if any
type	string	The format of the quiz answer Note: currently, we are only returning text-based quiz answers. In the future, we will also have image-based questions available.
content	string	Quiz question answer
distractor	boolean	Whether the multiple choice question response is the correct answer (false) or is a distractor (true)
matchOption	object	Matching options (LHS)
correctChoice	object	Matching options (RHS), indicating the correct choice
order	number	Indicates the correct ordering of the response
exitQuiz	array[object]	The exit quiz questions - which test on the knowledge learned in the lesson
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": "predicting-the-size-of-a-product",
    "lessonTitle": "Predicting the size of a product",
    "starterQuiz": [
      {
        "question": "Match the number to its written representation.",
        "questionType": "match",
        "answers": [
          {
            "matchOption": {
              "type": "text",
              "content": "seven tenths"
            },
            "correctChoice": {
              "type": "text",
              "content": "0.7"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "nine tenths"
            },
            "correctChoice": {
              "type": "text",
              "content": "0.9"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "seven ones"
            },
            "correctChoice": {
              "type": "text",
              "content": "7"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "seven hundredths"
            },
            "correctChoice": {
              "type": "text",
              "content": "0.07"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "nine hundredths"
            },
            "correctChoice": {
              "type": "text",
              "content": "0.09"
            }
          }
        ]
      }
    ],
    "exitQuiz": [
      {
        "question": "Use the fact that 9 × 8 = 72, to match the expressions to their product.",
        "questionType": "match",
        "answers": [
          {
            "matchOption": {
              "type": "text",
              "content": "9 × 80"
            },
            "correctChoice": {
              "type": "text",
              "content": "720"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "9 × 800 "
            },
            "correctChoice": {
              "type": "text",
              "content": "7,200"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "9 × 0.8"
            },
            "correctChoice": {
              "type": "text",
              "content": "7.2"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "9 × 0"
            },
            "correctChoice": {
              "type": "text",
              "content": "0"
            }
          },
          {
            "matchOption": {
              "type": "text",
              "content": "9 × 0.08"
            },
            "correctChoice": {
              "type": "text",
              "content": "0.72"
            }
          }
        ]
      }
    ]
  }
]

4.1 Quiz questions for a lesson
4.2 Quiz questions across a sequence
4.3 Quiz questions by key stage and subject

Quiz questions

4.1 Quiz questions for a lesson

GET /lessons/{lesson}/quiz

Inputs (path, query)

Output (response)

Sample response

4.2 Quiz questions across a sequence

GET /sequences/{sequence}/questions

Inputs (path, query)

Output (response)

Sample response

4.3 Quiz questions by key stage and subject

GET /key-stages/{keyStage}/subject/{subject}/questions

Inputs (path, query)

Output (response)

Sample response

Contents