Paid

Align text to subtopics

Name: Revision Genie AI Tutor
Author: Revision Genie

POST/api/v1/align1p

Scope: ai:align
Price: 1p per call

Match your own text, a lesson plan or a scheme of work, against one subject’s subtopics, and get back the closest matches with a ranking score.

What to know

`confidence` IS A RANKING SIGNAL WITHIN ONE RESPONSE, NOT A PROBABILITY. The best match in any response is 1 and the rest are relative to it, so a 0.6 in one response and a 0.6 in another are not comparable and neither is a percentage likelihood.
At most 8 matches are returned, best first.
An empty `matches` array is a successful answer meaning we found nothing in that subject resembling your text. It is not a failure and it is charged like any other call.
Identify the subject by id where you can. A name plus qualification plus board is supported for convenience, but an ambiguous name is refused rather than resolved to whichever row came back first.

Request body

Field	Type	Required	Description
content	string	Yes	The text to match. Up to 8,000 characters. Longer is refused rather than truncated, so send it in sections.
subjectId	string	No	The subject to match against. Either this, or the three fields below together.
subject	string	No	Subject name, for example "Biology". Used when you have no subjectId.
qualification	string	No	Narrows a subject name, for example "GCSE".
examBoard	string	No	Narrows a subject name, for example "AQA".

Example request

curl

curl -X POST "https://www.revisiongenie.com/api/v1/align" \
  -H "Authorization: Bearer rgk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"subjectId":"6612f0a1c3b4d5e6f7a80912","content":"Starter: recap the structure of a plant cell. Main: microscopy practical, calculate magnification."}'

Example response

json

{
  "subject": {
    "id": "6612f0a1c3b4d5e6f7a80912",
    "name": "Biology",
    "qualification": "GCSE",
    "examBoard": "AQA"
  },
  "matches": [
    {
      "subtopicId": "6612f0c3c3b4d5e6f7a80b01",
      "subtopic": "Cell structure",
      "topicId": "6612f0b2c3b4d5e6f7a80a01",
      "topic": "Cell biology",
      "confidence": 1
    },
    {
      "subtopicId": "6612f0c3c3b4d5e6f7a80b05",
      "subtopic": "Microscopy",
      "topicId": "6612f0b2c3b4d5e6f7a80a01",
      "topic": "Cell biology",
      "confidence": 0.62
    }
  ],
  "usage": { "costPence": 1, "balancePence": 4820 }
}

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
insufficient_balance	402	The balance does not cover the call. The body carries `balancePence` and a top-up link.
billing_not_enabled	403	The paid endpoints are not enabled on this developer account.
invalid_request	400	The body is not JSON, is not a JSON object, or a field failed validation. The message names the field.
request_too_large	413	The request body is larger than 32 KB.
subject_not_found	404	No active subject matches. A name that matches several subjects with no qualification or board given resolves to nothing rather than to a guess.
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.