Getting started

1. Join the programme. Sign in to Revision Genie, open /developers and fill in the short registration form: who you are, what you are building, and your agreement to the developer terms. The platform opens straight away.
2. Mint a key. On the platform, create a key, name it after where it will live, and tick the scopes it needs. The secret is shown once and never again, because we store only its hash. Copy it somewhere safe before you close the dialog.
3. Top up once. Your first top-up, of any amount we offer, unlocks the curriculum data endpoints on your account permanently. It is also the balance the paid endpoints spend from. Until then those four endpoints answer 402 topup_required.
4. Call the API. Send the key as a bearer token.

That returns every AQA GCSE subject we hold, each with an id. Those ids are what the rest of the API takes: feed one to /subjects/{id}/tree for its topics and subtopics, and a subtopic id to /subtopics/{id}/spec-points for the specification references it maps to.

The curriculum data endpoints are included once you have topped up, and cost nothing per call after that: your balance is not touched however many times you read them, and it reaching zero does not stop you. The endpoints that run a model, or that search on your behalf, come out of that prepaid balance: currently 1p for alignment calls, 4p for genie messages, 4p for chat messages and 8p for question sets. You top the balance up in pounds, a top-up adds to what you have rather than resetting it, and a call that fails through a fault on our side is not charged.

The full price list and the three ways to top up are on Billing and pricing.

• GET /api/v1/subjects list subjects
• GET /api/v1/subjects/{subjectId}/tree get a subject tree
• GET /api/v1/search search the catalogue
• GET /api/v1/subtopics/{subtopicId}/spec-points get specification references
• POST /api/v1/align align text to subtopics (1p)
• POST /api/v1/genies/{shortName}/chat chat with a subject genie (4p)
• POST /api/v1/chat chat without naming a genie (4p)
• POST /api/v1/questions/generate generate exam-style questions (8p)
• GET /api/v1/account read your account (free)

• Base URL https://www.revisiongenie.com/api/v1. Everything is JSON, and everything is versioned under /v1.
• Authentication is Authorization: Bearer rgk_live_... on every request. There are no cookies and no sessions.
• Errors are always { "error": "code", "message": "..." }. Branch on error; the message is for a person.
• Browsers can call these endpoints. Every response carries CORS headers and answers a preflight. Even so, keys belong on a server you control, never in a page or an app a user can read.
• Responses are private, no-store. They are answers to your key, so nothing shared may cache them.
• You may hold up to 5 live keys at once. Revoke one to mint another.

The chat endpoint is stateless: you send the whole conversation each time and we store none of it. It streams NDJSON by default, so pass stream: false while you are getting started.

• Authentication for keys, scopes and what you are responsible for.
• Errors and rate limits for every code you can receive and what is never charged.
• Legal for the developer terms, including attribution and what the API will never return.