API endpoints

Lists

The following lists are available to facilitate using other endpoints:

Key stages:
- Units by key stage and subject
- Lessons by key stage and subject
- Assets by key stage and subject
Subjects
- Specific subject
- Key stages by subject
- Sequences by subject
- Years by subject
Threads
- Units by thread

The top-level endpoints (key stages, subjects, threads) provide an overview of our data model, while the lower-level endpoints provide detailed information on specific subjects, key stages and threads.

1.1 Subjects

GET /subjects

This endpoint returns an array of all available subjects and their associated sequences, key stages and years.

Inputs

N/A

Output (response)

Name	Type	Description
0	object	The key stage 4 study pathway that this sequence represents. May be null.
subjectTitle	string	The subject title
subjectSlug	string	The subject slug identifier
sequenceSlugs	array[object]	Information about the years, key stages and key stage 4 variance for each sequence
sequenceSlug	string	The unique identifier for each sequence
years	array[number]	The years for which this subject has content available for
keyStages	array[object]	The key stage slug identifiers for which this subject has content available for.
keyStageTitle	string	The key stage title for the given key stage
keyStageSlug	string	The unique identifier for a given key stage
phaseSlug	string	The unique identifier for the phase to which this sequence belongs
phaseTitle	string	The title for the phase to which this sequence belongs
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

[
  {
    "subjectTitle": "Art and design",
    "subjectSlug": "art",
    "sequenceSlugs": [
      {
        "sequenceSlug": "art-primary",
        "years": [
          1,
          2,
          3,
          4,
          5,
          6
        ],
        "keyStages": [
          {
            "keyStageTitle": "Key Stage 1",
            "keyStageSlug": "ks1"
          },
          {
            "keyStageTitle": "Key Stage 2",
            "keyStageSlug": "ks2"
          }
        ],
        "phaseSlug": "primary",
        "phaseTitle": "Primary",
        "ks4Options": null
      },
      {
        "sequenceSlug": "art-secondary",
        "years": [
          7,
          8,
          9,
          10,
          11
        ],
        "keyStages": [
          {
            "keyStageTitle": "Key Stage 3",
            "keyStageSlug": "ks3"
          },
          {
            "keyStageTitle": "Key Stage 4",
            "keyStageSlug": "ks4"
          }
        ],
        "phaseSlug": "secondary",
        "phaseTitle": "Secondary",
        "ks4Options": null
      }
    ],
    "years": [
      1,
      2,
      3,
      4,
      5,
      6,
      7,
      8,
      9,
      10,
      11
    ],
    "keyStages": [
      {
        "keyStageTitle": "Key Stage 1",
        "keyStageSlug": "ks1"
      },
      {
        "keyStageTitle": "Key Stage 2",
        "keyStageSlug": "ks2"
      },
      {
        "keyStageTitle": "Key Stage 3",
        "keyStageSlug": "ks3"
      },
      {
        "keyStageTitle": "Key Stage 4",
        "keyStageSlug": "ks4"
      }
    ]
  }
]

1.2 Subject

GET /subjects/{subject}

This endpoint returns the sequences, key stages and years that are currently available for a given subject.

Inputs (path)

Name	Type	Description	Example
subject	string	The slug identifier for the subject	art

Output (response)

Name	Type	Description
0	object	The key stage 4 study pathway that this sequence represents. May be null.
subjectTitle	string	The subject title
subjectSlug	string	The subject slug identifier
sequenceSlugs	array[object]	Information about the years, key stages and key stage 4 variance for each sequence
sequenceSlug	string	The unique identifier for each sequence
years	array[number]	The years for which this subject has content available for
keyStages	array[object]	The key stage slug identifiers for which this subject has content available for.
keyStageTitle	string	The key stage title for the given key stage
keyStageSlug	string	The unique identifier for a given key stage
phaseSlug	string	The unique identifier for the phase to which this sequence belongs
phaseTitle	string	The title for the phase to which this sequence belongs
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

{
  "subjectTitle": "Art and design",
  "subjectSlug": "art",
  "sequenceSlugs": [
    {
      "sequenceSlug": "art-primary",
      "years": [
        1,
        2,
        3,
        4,
        5,
        6
      ],
      "keyStages": [
        {
          "keyStageTitle": "Key Stage 1",
          "keyStageSlug": "ks1"
        },
        {
          "keyStageTitle": "Key Stage 2",
          "keyStageSlug": "ks2"
        }
      ],
      "phaseSlug": "primary",
      "phaseTitle": "Primary",
      "ks4Options": null
    },
    {
      "sequenceSlug": "art-secondary",
      "years": [
        1,
        2,
        3,
        4,
        5,
        6
      ],
      "keyStages": [
        {
          "keyStageTitle": "Key Stage 1",
          "keyStageSlug": "ks1"
        },
        {
          "keyStageTitle": "Key Stage 2",
          "keyStageSlug": "ks2"
        }
      ],
      "phaseSlug": "secondary",
      "phaseTitle": "Secondary",
      "ks4Options": null
    }
  ],
  "years": [
    1,
    2,
    3,
    4,
    5,
    6,
    7,
    8,
    9,
    10,
    11
  ],
  "keyStages": [
    {
      "keyStageTitle": "Key Stage 1",
      "keyStageSlug": "ks1"
    },
    {
      "keyStageTitle": "Key Stage 2",
      "keyStageSlug": "ks2"
    },
    {
      "keyStageTitle": "Key Stage 3",
      "keyStageSlug": "ks3"
    },
    {
      "keyStageTitle": "Key Stage 4",
      "keyStageSlug": "ks4"
    }
  ]
}

1.3 Sequencing information for a given subject

GET /subjects/{subject}/sequences

This endpoint returns an array of sequence objects that are currently available for a given subject. For secondary sequences, this includes information about key stage 4 variance such as exam board sequences and non-GCSE ‘core’ unit sequences.

Inputs (path)

Name	Type	Description	Example
subject	string	The slug identifier for the subject	art

Output (response)

Name	Type	Description
0	object	The key stage 4 study pathway that this sequence represents. May be null.
sequenceSlug	string	The unique identifier for each sequence
years	array[number]	The years for which this subject has content available for
keyStages	array[object]	The key stage slug identifiers for which this subject has content available for.
keyStageTitle	string	The key stage title for the given key stage
keyStageSlug	string	The unique identifier for a given key stage
phaseSlug	string	The unique identifier for the phase to which this sequence belongs
phaseTitle	string	The title for the phase to which this sequence belongs
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

[
  {
    "sequenceSlug": "art-primary",
    "years": [
      1,
      2,
      3,
      4,
      5,
      6
    ],
    "keyStages": [
      {
        "keyStageTitle": "Key Stage 1",
        "keyStageSlug": "ks1"
      },
      {
        "keyStageTitle": "Key Stage 2",
        "keyStageSlug": "ks2"
      }
    ],
    "phaseSlug": "primary",
    "phaseTitle": "Primary",
    "ks4Options": null
  },
  {
    "sequenceSlug": "art-secondary",
    "years": [
      1,
      2,
      3,
      4,
      5,
      6
    ],
    "keyStages": [
      {
        "keyStageTitle": "Key Stage 1",
        "keyStageSlug": "ks1"
      },
      {
        "keyStageTitle": "Key Stage 2",
        "keyStageSlug": "ks2"
      }
    ],
    "phaseSlug": "secondary",
    "phaseTitle": "Secondary",
    "ks4Options": null
  }
]

1.4 Key stages within a subject

GET /subjects/{subject}/key-stages

This endpoint returns a list of key stages that are currently available for a given subject.

Inputs (path)

Name	Type	Description	Example
subject	string	The subject slug identifier	art

Output (response)

Name	Type	Description
keyStageTitle	string	The key stage title for the given key stage
keyStageSlug	string	The unique identifier for a given key stage
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

[
  {
    "keyStageTitle": "Key Stage 1",
    "keyStageSlug": "ks1"
  },
  {
    "keyStageTitle": "Key Stage 2",
    "keyStageSlug": "ks2"
  },
  {
    "keyStageTitle": "Key Stage 3",
    "keyStageSlug": "ks3"
  },
  {
    "keyStageTitle": "Key Stage 4",
    "keyStageSlug": "ks4"
  }
]

1.5 Year groups for a given subject

GET /subjects/{subject}/years

This endpoint returns an array of years that are currently available for a given subject.

Inputs (path)

Name	Type	Description	Example
subject	string	Subject slug to filter by	cooking-nutrition

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

[
  1,
  2,
  3,
  4,
  5,
  6,
  7,
  8,
  9
]

1.6 Key stages

GET /key-stages

This endpoint returns all the key stages (titles and slugs) that are currently available on Oak

Inputs

N/A

Output (response)

Name	Type	Description
slug	string	The key stage slug identifier
title	string	The key stage title
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

[
  {
    "slug": "ks1",
    "title": "Key Stage 1"
  }
]

1.7 Lessons

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

This endpoint returns an array of available published lessons for a given subject and key stage, grouped by unit.

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 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	word-class
offset [optional]	number	Limit the number of lessons returned per unit. Units with zero lessons after limiting are omitted.	50
limit [optional]	number	Offset applied to lessons within each unit (not to the unit list).	10

Output (response)

Name	Type	Description
unitSlug	string	The unit slug identifier
unitTitle	string	The unit title
lessons	array[object]	List of lessons for the specified unit
lessonSlug	string	The lesson slug identifier
lessonTitle	string	The lesson title
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

[
  {
    "unitSlug": "simple-compound-and-adverbial-complex-sentences",
    "unitTitle": "Simple, compound and adverbial complex sentences",
    "lessons": [
      {
        "lessonSlug": "four-types-of-simple-sentence",
        "lessonTitle": "Four types of simple sentence"
      },
      {
        "lessonSlug": "three-ways-for-co-ordination-in-compound-sentences",
        "lessonTitle": "Three ways for co-ordination in compound sentences"
      }
    ]
  }
]

1.8 Units

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

This endpoint returns an array of units containing available published lessons for a given key stage and subject, grouped by year. Units without published lessons will not be returned by this endpoint.

Inputs (path)

Name	Type	Description	Example
keyStage	string	Key stage slug to filter by, e.g. 'ks2'	ks1
subject	string	Subject slug to search by, e.g. 'science' - note that casing is important here (always lowercase)	art

Output (response)

Name	Type	Description
yearSlug	string	The year identifier
yearTitle	string	The year title
units	array[object]	List of units for the specified year
unitSlug	string	The unit slug identifier
unitTitle	string	The unit title
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

[
  {
    "units": [
      {
        "unitSlug": "2-4-and-8-times-tables-using-times-tables-to-solve-problems",
        "unitTitle": "2, 4 and 8 times tables: using times tables to solve problems"
      },
      {
        "unitSlug": "bridging-100-counting-on-and-back-in-10s-adding-subtracting-multiples-of-10",
        "unitTitle": "Bridging 100: counting on and back in 10s, adding/subtracting multiples of 10"
      }
    ],
    "yearSlug": "year-3",
    "yearTitle": "Year 3"
  }
]

1.9 Keywords

GET /keywords

This endpoint returns a list of keywords for a given key stage and subject, based on the keywords associated with the lessons that are available for that key stage and subject. The keywords are returned in order of frequency, with the most common keywords appearing first.

Inputs (query)

Name	Type	Example
subject [optional]	string
keyStage [optional]	string
phase [optional]	string
unit [optional]	string
lesson [optional]	string

Output (response)

N/A

1.10 Threads

GET /threads

This endpoint returns an array of all threads, across all subjects. Threads signpost groups of units that link to one another, building a common body of knowledge over time. They are an important component of how Oak’s curricula are sequenced.

Inputs

N/A

Output (response)

Name	Type	Description
title	string	The thread title
slug	string	The thread slug identifier
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

[
  {
    "title": "Number: Multiplication and division",
    "slug": "number-multiplication-and-division"
  }
]

1.11 Units belonging to a given thread

GET /threads/{threadSlug}/units

This endpoint returns all of the units that belong to a given thread.

Inputs (path)

Name	Type	Example
threadSlug	string	number-multiplication-and-division

Output (response)

Name	Type	Description
unitTitle	string	The unit title
unitSlug	string	The unit slug identifier
unitOrder	number	The position of the unit within the thread
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

[
  {
    "unitTitle": "Unitising and coin recognition - counting in 2s, 5s and 10s",
    "unitSlug": "unitising-and-coin-recognitions-counting-in-2s-5s-and-10s",
    "unitOrder": 1
  },
  {
    "unitTitle": "Solving problems in a range of contexts",
    "unitSlug": "unitising-and-coin-recognition-solving-problems-involving-money",
    "unitOrder": 2
  }
]

1.1 Subjects
1.2 Subject
1.3 Sequencing information for a given subject
1.4 Key stages within a subject
1.5 Year groups for a given subject
1.6 Key stages
1.7 Lessons
1.8 Units
1.9 Keywords
1.10 Threads
1.11 Units belonging to a given thread

Lists

1.1 Subjects

GET /subjects

Inputs

Output (response)

Sample response

1.2 Subject

GET /subjects/{subject}

Inputs (path)

Output (response)

Sample response

1.3 Sequencing information for a given subject

GET /subjects/{subject}/sequences

Inputs (path)

Output (response)

Sample response

1.4 Key stages within a subject

GET /subjects/{subject}/key-stages

Inputs (path)

Output (response)

Sample response

1.5 Year groups for a given subject

GET /subjects/{subject}/years

Inputs (path)

Output (response)

Sample response

1.6 Key stages

GET /key-stages

Inputs

Output (response)

Sample response

1.7 Lessons

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

Inputs (path, query)

Output (response)

Sample response

1.8 Units

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

Inputs (path)

Output (response)

Sample response

1.9 Keywords

GET /keywords

Inputs (query)

Output (response)

1.10 Threads

GET /threads

Inputs

Output (response)

Sample response

1.11 Units belonging to a given thread

GET /threads/{threadSlug}/units

Inputs (path)

Output (response)

Sample response

Contents