How to connect Oak National Academy MCP with Codex

Hybrid lexical and semantic search across lessons, units, threads and sequences, plus lexical typeahead suggestions (scoped) Required parameters: `scope` (which index to search) and `query` (your search query). For `threads` scope, `query` may be omitted if `subject` or `keyStage` is provided. SCOPE SELECTION — choose the right scope for the teacher's intent: - "lessons": Find specific lessons on a topic. Best for "find me a lesson about X". - "units": Find teaching units (groups of lessons). Best for "what units cover X?". - "threads": Find learning progression strands across year groups. Best for "how does X build across years?". If the teacher mentions a subject (for example, "maths threads"), pass it in the subject filter parameter rather than relying on the query alone. - "sequences": Find curriculum programme structures. Best for "show me the programme for X". Sequence names are structural (for example, "maths-secondary"), so broad subject terms should be passed via subject filters. - "suggest": Typeahead suggestions as the user types. Best for autocomplete. Use this when you need to: - Find lessons, units, threads, or sequences on a topic - Search with specific filters (key stage, subject, year, tier) - Get typeahead suggestions for a partial query - Discover what content exists for a subject or topic Do NOT use for: - Fetching known content by ID (use 'fetch') - Understanding the curriculum structure (use 'get-curriculum-model') - Browsing what's available without a search query (use 'browse-curriculum') - Exploring a topic across multiple indexes at once (use 'explore-topic') NATURAL LANGUAGE MAPPING EXAMPLES: - "Find KS3 science lessons about photosynthesis" → scope: 'lessons', query: 'photosynthesis', subject: 'science', keyStage: 'ks3' - "What units cover fractions in primary maths?" → scope: 'units', query: 'fractions', subject: 'maths', keyStage: 'ks2' - "What's the learning progression for algebra?" → scope: 'threads', query: 'algebra', subject: 'maths' - "What maths threads are there?" → scope: 'threads', subject: 'maths' (no query needed — returns all maths threads sorted by size) - "Show me secondary science programmes" → scope: 'sequences', query: 'science', keyStage: 'ks3' - "Find lessons on the Romans for Year 3" → scope: 'lessons', query: 'Romans', year: '3' - "KS4 higher tier maths on trigonometry" → scope: 'lessons', query: 'trigonometry', keyStage: 'ks4', tier: 'higher' SCOPE LIMITATIONS: - "suggest" requires at least one filter: subject or keyStage. - "sequences" works best with structural names (for example, "maths-secondary"), not topic words. - "threads" can omit query when subject or keyStage is provided, returning all matching threads sorted by unit count. CROSS-TOOL WORKFLOWS: - For lesson planning: search(scope: 'lessons') → fetch(lesson:slug) for full details - For prior knowledge: search(scope: 'threads') → get-prior-knowledge-graph with the found unit slugs for their stated prior knowledge - For progressions: search(scope: 'threads') → get-thread-progressions for ordered units NOTE: This tool can return a large payload at broad scope and may exceed a host's per-result token limit. Broad scopes such as `sequences` are largest; pass `size` to cap results and `from` to page.

Fetch curriculum resource by canonical identifier. Use this when you need to: - Get lesson details (learning objectives, keywords, misconceptions) - Get unit information (lessons list, subject context) - Get subject or sequence overview - Retrieve thread progression data Do NOT use for: - Finding content when you don't have the ID (use 'search') - Understanding ID formats (use 'get-curriculum-model') Use format "type:slug" (e.g., "lesson:add-fractions-with-the-same-denominator", "unit:comparing-fractions").

Returns a complete orientation to Oak National Academy's curriculum: domain model (key stages, subjects, entity hierarchy, property graph) AND tool usage guidance (categories, workflows, tips). Use this when you need to understand: - The Oak curriculum structure (key stages, subjects, units, lessons, threads) - Which tools are available and how to use them - Common workflows for finding and using curriculum content - How to interpret ID formats for the 'fetch' tool Do NOT use for: - Fetching actual curriculum content (use 'search' or 'fetch') - Looking up specific lessons, units, or resources

Returns how an Oak curriculum thread progresses across year groups, for the anchor you name. Threads connect units into conceptual progressions across years (160 threads across 17 subjects). A thread is a tag on units; the order is the curriculum's. Every call is anchored — exactly ONE of: - threadSlug: the detail anchor; returns that ONE thread's full unit progression as one run per subject the thread spans — never the whole thread estate. - subject + keyStage (both together): the discovery anchor; returns bounded thread descriptors (slug, title, year span, unit count, subjects — no sequences) so you can pick a threadSlug to anchor next. Ordering semantics: each run is Oak's curriculum order for that subject — years ascending (earliest → latest), and within a year the authored unit order of the subject's sequence; "All years" units follow the year-placed ones. A thread spanning subjects (the modern-language grammar and skill threads run through French, German and Spanish) returns parallel per-subject runs; Oak authors no order across subjects, so runs are never interleaved. At key stage 4 a unit merges its exam-board and tier variants into one node, so a KS4 run is a BIAS, not a guarantee: where boards order their units differently, the earliest authored position wins, and sibling variants of one topic can sit side by side. Read same-year order at KS4 as Oak's typical order, not any one board's. Slugs are corpus keys — resolve them first with search (scope "threads"), fetch, or browse-curriculum. An unknown threadSlug is reported in the result's unknownAnchors, not errored; an unmatched subject+keyStage returns a well-formed empty result. Use this to answer questions like: - "What's the learning path for fractions?" (discover with subject+keyStage, then anchor the thread) - "How does this thread build from early years to GCSE?" (threadSlug) - "Which threads cover algebra at KS3?" (subject + keyStage) Complements get-prior-knowledge-graph (each unit's stated prior knowledge) and get-misconception-graph (per-lesson misconceptions along a thread).

Returns the stated prior knowledge for the anchor units you name. "Prior knowledge of unit X" means what Oak records on the unit itself: the flat list of prior-knowledge statements — free-text propositions about what pupils are assumed to know or have experienced before the unit. Statements name knowledge, not the units that teach it; judging whether earlier units satisfy them is the caller's reasoning. The query is anchored, never whole-corpus: - unitSlugs: the anchor units. Slugs are corpus keys — resolve them first with search, fetch, or browse-curriculum. Unknown slugs are reported in the result's unknownAnchors, not errored. The result reports units — each with unitSlug, unitTitle, subject, keyStage, year (absent for the few units Oak records without one), priorKnowledge statements, and threadSlugs — plus resolvedAnchors and unknownAnchors. Coverage: some units record no prior-knowledge statements, so an empty priorKnowledge array means Oak states none for that unit — not that the unit is missing from the corpus. Likewise, some units belong to no thread, so an empty threadSlugs array means the unit has no get-thread-progressions context to follow. Use this to answer questions like: - "What should students know before this unit?" (anchor: that unit's slug) - "Which prerequisite gaps could explain difficulty with this lesson's unit?" - "What earlier units does this scheme of work build on?" (anchor the plan's units, then check the statements against earlier units' content) Complements get-thread-progressions: use each returned unit's threadSlugs (where non-empty) there to see how the concept builds across years.

Returns the misconceptions (with teacher responses) addressed by the anchor you name. Misconceptions are extracted per lesson from the Oak curriculum and reached through the thread → unit → lesson → misconception chain. Every call is anchored — exactly ONE of: - lessonSlugs: the leaf anchor; each lesson carries at most two misconceptions. - unitSlugs: the core anchor; each unit returns every placed lesson with its misconceptions, in Oak's authored teaching order (typical bodies 2–11 KB per unit). - threadSlug (+ optional unitOffset/unitLimit): a unit-granular window over one thread in Oak's curriculum order (years ascending within a subject, with units Oak places at no single year following the year-placed ones, then within a year the authored unit order — a unit node merges every board and tier and each unit takes its earliest recorded position where they disagree, so at KS4 the within-year order is a bias towards earliest placement, not any one board's order), default 10 units per page (maximum 25), with totalUnits and hasMore reported so partial coverage is always visible. unitOffset/unitLimit are valid ONLY with threadSlug — combining them with lessonSlugs or unitSlugs is rejected. Ordering is a deterministic projection of Oak's authored order, not a single global sequence. A thread's units are grouped by subject, each subject's run in curriculum order (years ascending — units Oak places at no single year, the PE swimming units, follow the year-placed ones — then within a year the authored unit order — where a unit's board and tier variants disagree each unit takes its earliest recorded position, so at KS4 the within-year order is a bias towards earliest placement and not any one board's order), and the runs are concatenated — Oak records no order ACROSS subjects, so the join between runs carries no pedagogical claim. A unit's lessons follow the authored lesson order of the programmes that place them; where variants disagree the earliest recorded position is used with a slug tie-break, and a lesson no variant orders follows the ordered ones. What this rules out is the alphabet: the order is never the id-sorted one it used to be. Slugs are corpus keys — resolve them first with search, fetch, or browse-curriculum. Unknown slugs are reported in the result's unknownAnchors, not errored. Coverage honesty: some units belong to no thread (unit entries carry threadSlugs membership; an empty list marks a thread-unreachable unit), so thread-anchored results are thread-scoped and never subject-complete. Use this to answer questions like: - "What misconceptions should I anticipate in this lesson?" (anchor: that lesson's slug) - "Which misconceptions does this unit address across its lessons?" - "How do misconceptions develop along this curriculum thread?" (windowed) Complements get-prior-knowledge-graph (prerequisite gaps) with per-lesson misconception detail.

Returns the key vocabulary for one teaching context: a bounded, frequency-ranked page of curriculum keywords, each decorated with its in-scope placing lessons. Every call is anchored by subject + keyStage (both required — corpus keys, e.g. "maths" + "ks2"), narrowable by unitSlugs and/or lessonSlugs. Ranking is by in-scope placement count (how many anchor-matching lessons place the keyword), descending — vocabulary frequent elsewhere in the curriculum never outranks locally relevant vocabulary. Results are bounded top-N (default 25, max 100) with honest totals (totalMatchingKeywords, hasMore); each entry carries the keyword node (term, description, global frequency = unique placing lessons corpus-wide, coarse firstYear at key-stage granularity: ks1→1, ks2→3, ks3→7, ks4→10) plus up to 10 in-scope placing lessons (hasMoreLessons marks the cut) — richness arrives by edge traversal on the curriculum graph, never a flat dump. Data is a point-in-time snapshot of the published curriculum (bulk export), not the live API; coverage can lag live content, materially at KS4 while subjects restructure. When to prefer which keywords tool: get-keywords returns the LIVE keyword set for a key stage + subject — fresh, authoritative at KS4, alphabetical, unranked, and paginated (its description carries the paging guidance; the complete set takes limit: 300 plus offset walking). This tool returns a bounded frequency-ranked subset with lesson connections — token-economical, best for "the most relevant vocabulary for this teaching context" and for navigating from keywords into lessons, units, and the wider curriculum graph. Slugs are corpus keys — resolve them first with search, fetch, or browse-curriculum. Unknown unitSlugs/lessonSlugs are reported in the result's unknown-anchor fields, not errored; an unknown subject or keyStage returns a well-formed empty result. Use this to answer questions like: - "What vocabulary should I emphasise teaching maths at KS2?" (subject + keyStage) - "Which keywords matter most in this unit?" (narrow with unitSlugs) - "What terms does this lesson rely on?" (narrow with lessonSlugs) Complements get-keywords (live set, paginated), get-misconception-graph, get-prior-knowledge-graph, and get-thread-progressions on the same curriculum graph.

Browse what's available in Oak's curriculum without searching. Returns structured facet data showing subjects, key stages, sequences (programmes), units, and lesson counts. Useful for orientation and discovery. Use this when: - The teacher wants to see what's available ("What subjects do you have?") - The teacher wants to browse a subject ("Show me the maths curriculum") - The teacher wants to see what's at a key stage ("What's in KS2?") - You need to understand curriculum structure before searching Do NOT use for: - Searching for specific content (use 'search' with a query) - Getting full lesson details (use 'fetch') - Understanding the domain model (use 'get-curriculum-model') NATURAL LANGUAGE MAPPING EXAMPLES: - "What subjects are available?" → no arguments (returns all facets) - "Show me KS2 science" → { subject: 'science', keyStage: 'ks2' } - "What's in the maths curriculum?" → { subject: 'maths' } - "What subjects are at Key Stage 3?" → { keyStage: 'ks3' } NOTE: This tool can return a large payload at broad scope and may exceed a host's per-result token limit. Pass `subject` and/or `keyStage` to narrow; an unfiltered call returns the whole curriculum.

Explore a topic across the entire Oak curriculum in one call. Searches lessons, units, AND learning threads in parallel for a topic, returning a unified topic map showing what's available across all scopes. Returns a small set from each scope (top 5) for a quick overview. Use this when: - The teacher says "What does Oak have about volcanos?" - The teacher says "I want to teach about electricity" - You need to discover what content exists before drilling down - The teacher's intent doesn't clearly map to one scope - The teacher mentions a subject and you need cross-scope results (pass the subject parameter explicitly) Do NOT use for: - Precise search in a single scope (use 'search' with a specific scope) - Browsing without a topic (use 'browse-curriculum') - Fetching known content by ID (use 'fetch') - Understanding the curriculum structure (use 'get-curriculum-model') NATURAL LANGUAGE MAPPING EXAMPLES: - "What does Oak have about volcanos?" → { query: 'volcanos' } - "Explore fractions across the curriculum" → { query: 'fractions', subject: 'maths' } - "Explore maths topics" → { query: 'topics', subject: 'maths' } - "I want to teach about electricity in KS3" → { query: 'electricity', keyStage: 'ks3' } - "What can you tell me about the Romans?" → { query: 'the Romans' } NEXT STEPS AFTER EXPLORE: - Use search(scope: 'lessons') for more lesson results - Use search(scope: 'threads') for progression details - Use fetch(lesson:slug) for full lesson content - Use get-thread-progressions for ordered unit sequences

Generate a short-lived, secure download link for a lesson asset. Returns a clickable URL valid for 5 minutes that downloads the asset directly in the user's browser — no authentication needed on their side. Use this when: - The user wants to download a slide deck, worksheet, quiz, or video - You have the lesson slug and asset type from a previous get-lessons-assets call Do NOT use for: - Browsing available assets (use 'get-lessons-assets') - Getting lesson content or metadata (use 'fetch')

All key stages Use when you need the master list of key stages. Returns every key stage with its title and slug. Not for: key stages restricted to a subject (GET /subjects/{subject}/key-stages).

Downloadable assets by key stage and subject Use when you want every downloadable asset for a key stage + subject, without programme structure or unit sequence order, optionally scoped to a unit or asset type. Returns assets grouped by lesson, each with signed download URLs, asset type, lesson title and slug, and attribution. Pass unit to restrict to one unit and type to restrict to one asset type (one of: 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: assets across a sequence (GET /sequences/{sequence}/assets); assets in one programme (GET /programmes/{programme}/assets); a single lesson's downloads (GET /lessons/{lesson}/assets); streaming one file (GET /lessons/{lesson}/assets/{type}). NOTE: The asset `url` fields returned by this tool are authenticated API endpoints and cannot be used as direct browser download links. To generate a clickable download link for the user, call the `download-asset` tool with the lesson slug and asset type. If `download-asset` is not available (e.g. stdio transport), direct users to the lesson page on the Oak website — use the lesson's `oakUrl` (e.g. `https://www.thenational.academy/teachers/lessons/{lessonSlug}`). NOTE: This tool can return a large payload at broad scope and may exceed a host's per-result token limit. Narrow with `unit` and/or `type` (asset type), or use `get-lessons-assets` for one lesson.

List lessons in a key stage and subject Use when you want every published lesson in a key stage + subject, grouped by unit, without programme structure or unit sequence order. Returns an array of units, each with slug, title, and the lessons inside. Pass unit to restrict to one. Supports offset/limit pagination; Link: rel="next" header signals more pages. Not for: finding a lesson from a search term (GET /search/lessons); a single lesson's metadata (GET /lessons/{lesson}/summary); all units across a sequence (GET /sequences/{sequence}/units); units in one programme (GET /programmes/{programme}/units). Example: keyStage=ks3, subject=maths, unit=perimeter-and-area.

Quiz questions by key stage and subject 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 /programmes/{programme}/questions).

Units in a key stage and subject Use when you want a flat list of every unit with published lessons in a key stage + subject, without programme structure or unit sequence order. Returns units grouped by year slug; units without published lessons are omitted. Pass examBoard to restrict KS4 to one board (one of: aqa, edexcel (Edexcel A), eduqas, ocr, wjec, edexcelb (Edexcel B)); otherwise each unit lists the boards it appears in. Not for: all units across a sequence (GET /sequences/{sequence}/units); units in one programme (GET /programmes/{programme}/units); a single unit (GET /units/{unit}/summary); lessons rather than units (GET /key-stages/{keyStage}/subject/{subject}/lessons); units in a thread (GET /threads/{threadSlug}/units).

Keywords by subject and key stage Use when you want the vocabulary for a key stage, subject, unit, lesson, or phase — e.g. to build a glossary or attach definitions to content. Returns keywords with definition, the subject + key stage they appear in, and the lessons that use them, sorted alphabetically. All filters are optional, but pass at least one of keyStage, subject, unit, lesson, or phase. Request rules: - At least one of subject, keyStage, phase, unit or lesson must be provided - note that they are all the slug form of the values (e.g. "ks2" for key stage 2, "science" for the science subject, and "forces-and-magnets" for the forces and magnets unit), and that casing is important (always lowercase). WHEN TO PREFER WHICH KEYWORDS TOOL: this tool returns the LIVE keyword set for a key stage + subject — fresh and authoritative (including KS4 during curriculum restructures), alphabetical, unranked, and large at subject scope. For a bounded frequency-ranked subset with lesson connections (token economy + relationship navigation over the curriculum graph), prefer get-keyword-graph, which serves a point-in-time curriculum snapshot. NOTE: This tool is paginated — the server returns at most 20 keywords unless you pass `limit` (max 300). The result's `pagination` field reports `hasMore` and, when more pages exist, the `nextOffset`/`nextLimit` to pass; follow it until `hasMore` is false. Do not infer completeness by counting items against your limit.

Downloadable assets for a lesson 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 /programmes/{programme}/assets); lesson metadata (GET /lessons/{lesson}/summary). NOTE: The asset `url` fields returned by this tool are authenticated API endpoints and cannot be used as direct browser download links. To generate a clickable download link for the user, call the `download-asset` tool with the lesson slug and asset type. If `download-asset` is not available (e.g. stdio transport), direct users to the lesson page on the Oak website — use the lesson's `oakUrl` (e.g. `https://www.thenational.academy/teachers/lessons/{lessonSlug}`).

Quiz questions for a lesson 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 /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).

Lesson summary by slug 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.

Lesson video 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).

Get a programme by slug Use when you need to get the metadata of one programme. Get programme slugs from GET /subjects/{subject}/programmes. Returns the programme's year group, slug (e.g. y7, y10-biology-foundation), and applicable programme factors (exam board, tier, child subject). Not for: the units, questions, or assets of one programme (GET /programmes/{programme}/units, GET /programmes/{programme}/questions, or GET /programmes/{programme}/assets); the sequence-level summary (GET /sequences/{sequence}); all programmes for a subject (GET /subjects/{subject}/programmes). NOTE: Programme slugs are the full form — `<subject>-<phase>-year-<year>` plus any KS4 factor — e.g. `english-secondary-year-7` or `english-secondary-year-10-edexcel`, not the short `y7` shorthand used above. Pass the exact slug string this response returns to `get-programmes` and its sub-endpoints.

Downloadable assets in a programme Use when you need every downloadable asset for a single programme (year group) within a subject. Returns assets grouped by lesson with signed download URLs, asset type, lesson title and slug, and attribution. Supports offset/limit pagination; Link: rel="next" header signals more pages. Optionally narrow by asset type (one of: 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: assets across a whole sequence (GET /sequences/{sequence}/assets); assets for a key stage + subject without programme structure (GET /key-stages/{keyStage}/subject/{subject}/assets); a single lesson's downloads (GET /lessons/{lesson}/assets); streaming one file (GET /lessons/{lesson}/assets/{type}). NOTE: The asset `url` fields returned by this tool are authenticated API endpoints and cannot be used as direct browser download links. To generate a clickable download link for the user, call the `download-asset` tool with the lesson slug and asset type. If `download-asset` is not available (e.g. stdio transport), direct users to the lesson page on the Oak website — use the lesson's `oakUrl` (e.g. `https://www.thenational.academy/teachers/lessons/{lessonSlug}`).

Quiz questions in a programme Use when you want every quiz question in a single programme (year group) within a subject. Get programme slugs from GET /subjects/{subject}/programmes. Returns questions grouped by lesson with starter and exit quiz questions and answers. Supports offset/limit pagination; Link: rel="next" header signals more pages. Not for: questions in a single lesson (GET /lessons/{lesson}/quiz); questions across a whole sequence (GET /sequences/{sequence}/questions); questions for a key stage + subject without programme structure (GET /key-stages/{keyStage}/subject/{subject}/questions).

Units in a programme Use when you need the unit sequence for one programme — units as an ordered arrangement designed to build knowledge progressively. Get programme slugs from GET /subjects/{subject}/programmes. Returns units in unit sequence order with title, slug, and any associated factors. Not for: every unit across the whole sequence (GET /sequences/{sequence}/units); a flat list of units for a key stage + subject without programme structure (GET /key-stages/{keyStage}/subject/{subject}/units); a single unit (GET /units/{unit}/summary); units in a thread (GET /threads/{threadSlug}/units).

Current rate-limit status Use when you need rate-limit status as a JSON body — e.g. for a quota indicator. Returns limit, remaining, and reset. The same data sits on the 'X-RateLimit-*' headers of every response, so this tool is rarely needed directly. Does not count against your quota. NOTE: A response of limit=0, remaining=0, reset=0 indicates an unlimited API key with no rate cap.

Sequencing information for a given sequence slug Use when you have a sequence slug and need the sequence-level summary. A sequence is a subject's curriculum across a phase (e.g. maths-primary, science-secondary-aqa); it spans one or more National Curriculum schemes and contains one programme per year group. Get sequence slugs from GET /subjects or GET /subjects/{subject} (the sequenceSlugs field). Returns slug, phase, key stages, years, and any KS4 programme factors (exam board, tier, child subject, pathway) needed to interpret the programmes within it. Not for: the programmes within this sequence (GET /subjects/{subject}/programmes); the unit sequence for one programme (GET /programmes/{programme}/units); all units across the sequence (GET /sequences/{sequence}/units); subject-level catalogue data (GET /subjects or GET /subjects/{subject}). Example: sequence=maths-primary or science-secondary-aqa.

Downloadable assets in a sequence Use when you need every downloadable asset across a whole sequence — all programmes combined. Returns assets grouped by lesson in unit sequence order, with signed download URLs, asset type, lesson title and slug, and attribution. Pass year as an optional filter. Narrow further with type (one of: 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: assets in a single programme (GET /programmes/{programme}/assets); a single lesson's downloads (GET /lessons/{lesson}/assets); streaming one file (GET /lessons/{lesson}/assets/{type}); assets for a key stage + subject without programme structure (GET /key-stages/{keyStage}/subject/{subject}/assets). NOTE: The asset `url` fields returned by this tool are authenticated API endpoints and cannot be used as direct browser download links. To generate a clickable download link for the user, call the `download-asset` tool with the lesson slug and asset type. If `download-asset` is not available (e.g. stdio transport), direct users to the lesson page on the Oak website — use the lesson's `oakUrl` (e.g. `https://www.thenational.academy/teachers/lessons/{lessonSlug}`). NOTE: This tool can return a large payload at broad scope and may exceed a host's per-result token limit. Narrow with `year` and/or `type` (asset type), or use `get-lessons-assets` for one lesson.

Quiz questions across a sequence 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 /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).

Units in a curriculum sequence Use when you want every unit across a whole sequence — all programmes combined, in unit sequence order. Returns units grouped by programme (year group) in unit sequence order. If the sequence slug includes an exam board (e.g. science-secondary-aqa), units are scoped to that exam board. Secondary sequences also expose tiers, pathways, and exam subjects where applicable. Pass year as an optional filter to return only that year's units (across all KS4 factor combinations). Not for: units in a single programme (GET /programmes/{programme}/units); a flat list of units for a key stage + subject without programme structure or unit sequence order (GET /key-stages/{keyStage}/subject/{subject}/units); the programmes within this sequence (GET /subjects/{subject}/programmes); a single unit (GET /units/{unit}/summary); units in a thread (GET /threads/{threadSlug}/units). Example: sequence=science-secondary-aqa or maths-primary.

Single subject with sequences, key stages, and years Use when you have a subject slug. Returns subjectTitle, subjectSlug, sequenceSlugs, keyStages, and years. sequenceSlugs lists the sequences available for this subject; each sequence contains one programme per year group — call GET /subjects/{subject}/programmes to enumerate them. Not for: every subject in one call (GET /subjects); the key stages or year groups for a subject (GET /subjects/{subject}/key-stages or GET /subjects/{subject}/years); subject-scoped lessons or units (GET /key-stages/{keyStage}/subject/{subject}/lessons or GET /key-stages/{keyStage}/subject/{subject}/units); the detail of one sequence (GET /sequences/{sequence}). Example: subject=maths.

All subjects Use when you need every subject in one call — the entry point for a subject picker or for crawling the whole curriculum. Returns subjects alphabetically, each with subjectTitle, subjectSlug, sequenceSlugs, keyStages, and years. sequenceSlugs lists the sequences available for that subject; each sequence contains one programme per year group — call GET /subjects/{subject}/programmes to enumerate them. Not for: a single subject (GET /subjects/{subject}); the key stages or year groups for a subject (GET /subjects/{subject}/key-stages or GET /subjects/{subject}/years); lessons or units inside a subject (GET /key-stages/{keyStage}/subject/{subject}/lessons or GET /key-stages/{keyStage}/subject/{subject}/units); the detail of one sequence (GET /sequences/{sequence}).

Key stages for a subject Use when you only need the key stages where this subject is available. Returns key-stage titles and slugs. Not for: every key stage (GET /key-stages); the subject record (GET /subjects/{subject}). Example: 'subject=history'.

Get all programmes for a subject slug Use when you need to discover the programmes within a subject — to get a programme's slug for use with GET /programmes/{programme} or its sub-endpoints. Returns programmes grouped by key stage, each with year group, slug (e.g. y7, y10-biology-foundation), and applicable programme factors (exam board, tier, child subject). Not for: the metadata of one programme (GET /programmes/{programme}); the units, questions, or assets of one programme (GET /programmes/{programme}/units, GET /programmes/{programme}/questions, or GET /programmes/{programme}/assets); the sequence-level summary (GET /sequences/{sequence}). NOTE: Programme slugs are the full form — `<subject>-<phase>-year-<year>` plus any KS4 factor — e.g. `english-secondary-year-7` or `english-secondary-year-10-edexcel`, not the short `y7` shorthand used above. Pass the exact slug string this response returns to `get-programmes` and its sub-endpoints.

Year groups for a subject Use when you only need the year groups where this subject is available. Returns an array of year numbers, derived from the subject's key stages. Not for: the subject record (GET /subjects/{subject}); key stages rather than year groups (GET /subjects/{subject}/key-stages). Example: 'subject=english'.

All threads Use when you want the catalogue of every thread. A thread is an attribute on a unit that groups units across the curriculum to build a common body of knowledge — making vertical connections across year groups. Returns all threads with published units, sorted alphabetically — each with title, slug, and unitCount. Not for: the units inside a thread (GET /threads/{threadSlug}/units).

Units in a thread Use when you want every unit in a thread. A thread is an attribute on a unit that groups units across the curriculum to build a common body of knowledge — for example, number and place value or scientific method. Units in a thread span multiple programmes and key stages; thread order is independent of unit sequence order within any individual programme. Returns units in thread order with unitTitle, unitSlug, and unitOrder. Not for: the catalogue of threads (GET /threads); all units across a sequence (GET /sequences/{sequence}/units); units in one programme (GET /programmes/{programme}/units); a single unit (GET /units/{unit}/summary). Example: 'threadSlug=number-and-place-value'.

Unit summary by slug Use when you have a unit slug and need the unit summary: title, description, key stage, subject, year, threads, prior-knowledge requirements, national-curriculum statements, and the lessons inside. Unit variant slugs (ending in -1, -2, etc.) resolve to that specific variant. Not for: listing every unit in a key stage + subject (GET /key-stages/{keyStage}/subject/{subject}/units); all units across a sequence (GET /sequences/{sequence}/units); units in one programme (GET /programmes/{programme}/units); units in a thread (GET /threads/{threadSlug}/units); lessons inside the unit (GET /key-stages/{keyStage}/subject/{subject}/lessons with unit={unit}).

Use when a user asks to understand the Oak project, effort, or ecosystem — this repository, how Oak builds and delivers its curriculum, the project's purpose and machinery, or how to engage or contribute. Not for curriculum content questions (subjects, units, lessons, key stages, sequencing) — those are served by the curriculum tools.