Included

Get specification references

Name: Revision Genie AI Tutor
Author: Revision Genie

GET/api/v1/subtopics/{subtopicId}/spec-pointsIncluded

Scope: curriculum:read
Price: Included once you've topped up

The specification reference codes a subtopic is mapped to, with the unit they sit in and a link to the exam board’s own published document.

What to know

NO BOARD WORDING IS RETURNED, EVER. You get reference codes, unit names, our mapping and a link to the board’s own document. Exam board specification text is board copyright and it does not cross this API.
`mapped: false` WITH A 200 IS THE COMMON CASE, NOT AN ERROR. Most subtopics carry no mapping, and the honest answer is an empty `points` array with `mapped` false. Handle it as a normal response.
MAPPING IS ROLLING OUT SUBJECT BY SUBJECT. Every subtopic on a subject we have mapped resolves; a subject we have not reached yet answers `mapped: false` throughout. Build for both from the start rather than treating an unmapped subject as a fault, and ask us at support@revisiongenie.com where a subject you depend on has got to.
`unresolved` counts references that could not be found in the current specification skeleton. It means the specification was re-extracted and some references are being remapped, so your coverage of that subtopic is partial rather than short.
`ref` is a citation label, not a permanent key. Reference ids are positional within one extraction and are renumbered when a board reissues a specification.
A mapping claiming more than 200 references is truncated, and the response says so with `truncated: true`.
`specSource.url` is null when we hold no link we are willing to pass on. We link to the board’s own site, never to our copy of their document.

Parameters

Field	Type	Required	Description
subtopicId	string (path)	Yes	A 24-character hex id from either tree. The response reports which hierarchy it belongs to.

Example request

curl

curl "https://www.revisiongenie.com/api/v1/subtopics/6612f0c3c3b4d5e6f7a80b01/spec-points" \
  -H "Authorization: Bearer rgk_live_YOUR_KEY_HERE"

Example response

json

{
  "subtopic": {
    "id": "6612f0c3c3b4d5e6f7a80b01",
    "name": "Cell structure"
  },
  "hierarchy": "curriculum",
  "mapped": true,
  "specSource": {
    "board": "AQA",
    "url": "https://www.aqa.org.uk/subjects/science/gcse/biology-8461/specification"
  },
  "points": [
    {
      "ref": "4.1.1:2",
      "unitRef": "4.1.1",
      "unitTitle": "Cell structure",
      "kind": "content"
    },
    {
      "ref": "4.1.1:3",
      "unitRef": "4.1.1",
      "unitTitle": "Cell structure",
      "tier": "higher"
    }
  ],
  "unresolved": 1
}

Errors

Every error carries the same shape: a stable error code to branch on and a message for a human. Codes specific to this endpoint come first.

Code	Status	When
topup_required	402	This developer account has never topped up. The data endpoints are included from your first top-up onwards, whatever your balance does afterwards. The body carries a top-up link.
invalid_id	400	subtopicId is not a 24-character hex id.
not_found	404	No subtopic with that id in either hierarchy.
invalid_key	401	The key is missing, malformed, revoked, expired, or is not a developer key.
forbidden	403	The key is valid but does not hold the scope this endpoint requires.
suspended	403	The developer account is suspended. Data reads stop as well as billable calls.
rate_limited	429	The key went past its ceiling: 120 calls a minute overall, 30 a minute on the paid endpoints. Also returned after repeated failed authentication from one address.
server_error	500	Something failed on our side. Retry; a paid call is refunded.