{"openapi":"3.0.3","info":{"title":"Beacon by nexaBridge.ai","version":"5.0.0","description":"Three independent ways to evaluate a child's Hindi/English reading and\nMath ability from voice recordings — pick whichever fit(s):\n\n\n**ASER** (`/api/aser/...`) — adaptive, ASER-style. A session climbs or\ndescends a 5-rung ladder per subject (Hindi reading, English reading,\nMath), one recording at a time, finalizing at the highest level the\nchild demonstrably passed. Fast (2-4 items per subject) and produces a\nsingle categorical level per subject.\n\n\n**EGRA** (`/api/egra/...`) — a fixed, non-adaptive battery of timed\nreading-fluency subtasks (letter naming, nonsense-word decoding, oral\nreading — reported as correct-items-per-minute) plus comprehension\nquestions. Administered in one language per session, matching how real\nEGRA instruments are normed. Every item in the battery is presented up\nfront and answered once.\n\n\n**EGMA** (`/api/egma/...`) — a fixed, non-adaptive numeracy battery\n(quantity discrimination, missing number, arithmetic fluency). EGRA and\nEGMA are genuinely distinct instruments — EGMA is its own session\ntype/endpoint, not a numeracy section bolted onto an EGRA session, so\na caller wanting only reading or only numeracy never has to touch the\nother's content.\n\n\n### Authentication\n\n\nEvery `/api` request needs an API key, sent as\n`Authorization: Bearer <key>`. Sign up at `/signup`; once the Beacon\nteam approves your account, create keys at `/dashboard` (each key is\nshown once — store it on your server, never in a browser or app). A\nmissing, revoked or unapproved key gets a `401`. Adding to the content\nbank (`POST /api/*/content/...`) is limited to admin accounts (`403`\notherwise); reading it is open to every key.\n\n\n### Your data, not Beacon's\n\n\nA child is identified only by an opaque `childId` — none of the three\nschemes manage student profiles, and Beacon is not a store of\nassessment history:\n\n\n- A session is only visible to the account whose key created it —\n  anyone else gets a `404`.\n- Every submit returns the scored attempt and the updated session\n  (including the final result once it completes). Save what you need\n  from those responses; there is no \"list sessions\" endpoint.\n- Recordings are transcribed and scored, then discarded — keep your own\n  copy if you need it.\n- Completed sessions are deleted 24 hours after completion, and\n  in-progress sessions after 15 minutes without an answer.\n\n\n**Scoring is a draft rubric** in all three schemes, not sourced from an\nofficial ASER/EGRA/EGMA scoring guide — see README.md.\n\n\n### ASER level ladders\n\n\nBoth ladders use the same `LEVEL_0`–`LEVEL_4` names, low to high. A\nreading `LEVEL_2` and a math `LEVEL_2` are never compared to each\nother — the tables below are what actually distinguishes them. Fetch\nboth with labels at runtime via `GET /api/aser/reference/levels`\nrather than hardcoding this table in a client.\n\n\n**Reading** (Hindi & English use the same ladder, scored independently\nper language):\n\n\n| Level | Meaning |\n| --- | --- |\n| `LEVEL_0` | Cannot recognise letters |\n| `LEVEL_1` | Can read letters |\n| `LEVEL_2` | Can read words |\n| `LEVEL_3` | Can read a Std I level paragraph |\n| `LEVEL_4` | Can read a Std II level story |\n\n\n**Math**\n\n\n| Level | Meaning |\n| --- | --- |\n| `LEVEL_0` | Cannot recognise numbers |\n| `LEVEL_1` | Can recognise numbers 1-99 |\n| `LEVEL_2` | Can do 2-digit subtraction without borrowing |\n| `LEVEL_3` | Can do 2-digit subtraction with borrowing |\n| `LEVEL_4` | Can do 3-digit by 1-digit division |\n\n\n`LEVEL_0` has no content of its own — it's the floor a track finalizes\nat after failing `LEVEL_1`, not a level with a passage/problem to\npresent — so it can't be passed as `hindiReadingStartLevel` /\n`englishReadingStartLevel` / `mathStartLevel` (only `LEVEL_1`-`LEVEL_4`\nare valid start levels).\n\n\n### EGRA item kinds\n\n\nEGRA isn't leveled like ASER — every child gets the same fixed battery,\nand each item kind is scored a different way:\n\n\n| Item kind | What it measures |\n| --- | --- |\n| `LETTER_NAMING_FLUENCY` | Correct letters named per minute |\n| `NONSENSE_WORD_FLUENCY` | Correct decodable nonsense words read per minute |\n| `ORAL_READING_FLUENCY` | Correct words read per minute from a passage |\n| `READING_COMPREHENSION_QUESTION` | Right/wrong, about the oral-reading passage |\n| `LISTENING_PASSAGE` | No attempt — read aloud to the child, not by them |\n| `LISTENING_COMPREHENSION_QUESTION` | Right/wrong, about the passage read to the child |\n\n\n### EGMA item kinds\n\n\nSame idea for EGMA's numeracy battery — fixed, not leveled:\n\n\n| Item kind | What it measures |\n| --- | --- |\n| `QUANTITY_DISCRIMINATION` | Right/wrong — can the child pick the larger of two numbers |\n| `MISSING_NUMBER` | Right/wrong — can the child find the missing term in a number sequence |\n| `ARITHMETIC_FLUENCY` | Correct arithmetic answers per minute |\n"},"servers":[{"url":"https://beacon-assess.com","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"ASER Sessions"},{"name":"ASER Content"},{"name":"ASER Reference"},{"name":"EGRA Sessions"},{"name":"EGRA Content"},{"name":"EGMA Sessions"},{"name":"EGMA Content"},{"name":"Health"}],"paths":{"/health":{"get":{"tags":["Health"],"summary":"Liveness check","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}}}}},"/api/aser/sessions":{"post":{"tags":["ASER Sessions"],"summary":"Start an adaptive evaluation session for a child","description":"Creates a session with one adaptive track per subject (Hindi reading, English reading, Math). Reading tracks start at LEVEL_3 (as in ASER) unless overridden. The Math track is rated (Elo-style): it starts at rating 1000 (2-digit subtraction without borrowing), or at `mathStartRating` to carry a child's rating over, moves after every answer, and ends once the rating settles (usually 5-9 questions, at most 12). Math questions are generated and written in symbols only, e.g. \"52 - 27 = ?\". The response includes the first item to present for every track.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAserSessionInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AserSession"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}}},"/api/aser/sessions/{id}":{"parameters":[{"$ref":"#/components/parameters/SessionId"}],"get":{"tags":["ASER Sessions"],"summary":"Get a session, including each track's full attempt history","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AserSessionWithHistory"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/aser/sessions/{id}/tracks/{subject}/attempts":{"parameters":[{"$ref":"#/components/parameters/SessionId"},{"name":"subject","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Subject"}}],"post":{"tags":["ASER Sessions"],"summary":"Submit an answer for the track's current item","description":"Reading (Hindi/English) tracks require a voice recording — fluency is a property of spoken reading. MATH accepts either a voice recording OR a JSON text answer, whichever is more reliable for the calling app; a spoken numeric answer is transcribed and parsed the same way either way. Advances the track to the next level or finalizes it; once every track is finalized the session completes and `session.result` is populated.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["audio"],"properties":{"audio":{"type":"string","format":"binary","description":"mp3, wav, webm, ogg, or flac — max 15MB. mp4/m4a is accepted by the upload step but currently only works with ASR_PROVIDER=openai; Google's Speech-to-Text v1 API has no AAC/M4A support and will 400 on it.\n"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/SubmitTextAnswerInput"},"example":{"answer":"47"}}}},"responses":{"201":{"description":"Scored","content":{"application/json":{"schema":{"type":"object","properties":{"attempt":{"$ref":"#/components/schemas/Attempt"},"session":{"$ref":"#/components/schemas/AserSession"}}}}}},"400":{"description":"Validation failed, no audio/answer provided, a text answer for a reading subject, unsupported audio type, or the session/track is already completed\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"The track advanced to a different level while this answer was being processed (a concurrent submission won the race) — refetch the session and try again\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The speech-to-text provider call failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The configured ASR provider is missing its credentials, or no content exists in the bank for the track's current level\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/aser/content/reading-items":{"post":{"tags":["ASER Content"],"summary":"Add a reading passage to the content bank","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReadingItemInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadingItem"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["ASER Content"],"summary":"List reading passages","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"subject","in":"query","schema":{"$ref":"#/components/schemas/ReadingSubject"}},{"name":"level","in":"query","schema":{"$ref":"#/components/schemas/ReadingLevel"}}],"responses":{"200":{"description":"Paginated list of reading passages","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ReadingItem"}}}}]}}}}}}},"/api/aser/content/math-items":{"post":{"tags":["ASER Content"],"summary":"Add a math problem to the content bank","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMathItemInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathItem"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["ASER Content"],"summary":"List math problems","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"level","in":"query","schema":{"$ref":"#/components/schemas/MathLevel"}}],"responses":{"200":{"description":"Paginated list of math problems","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MathItem"}}}}]}}}}}}},"/api/aser/reference/levels":{"get":{"tags":["ASER Reference"],"summary":"Level ladders with human-readable labels","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceLevels"}}}}}}},"/api/egra/sessions":{"post":{"tags":["EGRA Sessions"],"summary":"Start a fixed EGRA reading battery for a child, in one language","description":"Assembles the full battery up front (letter naming, nonsense-word, oral reading + its comprehension questions, a listening passage + its comprehension questions) and returns every item to answer. Unlike ASER, nothing here is adaptive. For numeracy, see the separate `/api/egma/sessions` endpoint — EGMA is not part of this battery.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEgraSessionInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EgraSession"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"503":{"description":"The content bank is missing a subtask required for this battery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/egra/sessions/{id}":{"parameters":[{"$ref":"#/components/parameters/SessionId"}],"get":{"tags":["EGRA Sessions"],"summary":"Get a session and every item's current state/result","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EgraSession"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/egra/sessions/{id}/items/{itemId}/attempts":{"parameters":[{"$ref":"#/components/parameters/SessionId"},{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["EGRA Sessions"],"summary":"Submit an answer for one battery item","description":"Which input modes are accepted depends on the item's `kind` (see `allowedInputModes` on the item): fluency kinds (LETTER_NAMING_FLUENCY, NONSENSE_WORD_FLUENCY, ORAL_READING_FLUENCY) are voice-only; comprehension questions accept voice or text. LISTENING_PASSAGE items have no attempt at all. Each item can be answered at most once. Once every attemptable item in the session has a result, the session completes and `session.result` is populated with the aggregated report.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["audio"],"properties":{"audio":{"type":"string","format":"binary","description":"mp3, wav, webm, ogg, or flac — max 15MB"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/SubmitTextAnswerInput"},"example":{"answer":"cow"}}}},"responses":{"201":{"description":"Scored","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/EgraResult"},"session":{"$ref":"#/components/schemas/EgraSession"}}}}}},"400":{"description":"Validation failed, wrong input mode for this item's kind, the item already has a result, the item is a LISTENING_PASSAGE (no attempt), or the session is already completed\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"A concurrent submission already answered this item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The speech-to-text provider call failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The configured ASR provider is missing its credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/egra/content/fluency-items":{"post":{"tags":["EGRA Content"],"summary":"Add a letter grid / nonsense-word list / passage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFluencyItemInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FluencyItem"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["EGRA Content"],"summary":"List fluency items","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"subtaskType","in":"query","schema":{"$ref":"#/components/schemas/FluencySubtaskType"}},{"name":"language","in":"query","schema":{"$ref":"#/components/schemas/ReadingSubject"}}],"responses":{"200":{"description":"Paginated list of fluency items","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FluencyItem"}}}}]}}}}}}},"/api/egra/content/comprehension-questions":{"post":{"tags":["EGRA Content"],"summary":"Add a comprehension question for an ORAL_READING or LISTENING_PASSAGE item","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateComprehensionQuestionInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComprehensionQuestion"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["EGRA Content"],"summary":"List comprehension questions","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"fluencyItemId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Paginated list of comprehension questions","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ComprehensionQuestion"}}}}]}}}}}}},"/api/egma/sessions":{"post":{"tags":["EGMA Sessions"],"summary":"Start a fixed EGMA numeracy battery for a child, in one language","description":"Assembles the full battery up front (3 quantity-discrimination items, 3 missing-number items, and an arithmetic-fluency set) and returns every item to answer. Unlike ASER, nothing here is adaptive. This is a separate session type from EGRA — no reading items appear here, and an EGRA session never contains numeracy items.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEgmaSessionInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EgmaSession"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"503":{"description":"The content bank is missing a subtask required for this battery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/egma/sessions/{id}":{"parameters":[{"$ref":"#/components/parameters/SessionId"}],"get":{"tags":["EGMA Sessions"],"summary":"Get a session and every item's current state/result","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EgmaSession"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/egma/sessions/{id}/items/{itemId}/attempts":{"parameters":[{"$ref":"#/components/parameters/SessionId"},{"name":"itemId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"tags":["EGMA Sessions"],"summary":"Submit an answer for one battery item","description":"Which input modes are accepted depends on the item's `kind` (see `allowedInputModes` on the item): QUANTITY_DISCRIMINATION and MISSING_NUMBER accept voice or text; ARITHMETIC_FLUENCY is voice-only (a timed, multi-problem recording, not a single-answer question). Each item can be answered at most once. Once every item in the session has a result, the session completes and `session.result` is populated with the aggregated report.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["audio"],"properties":{"audio":{"type":"string","format":"binary","description":"mp3, wav, webm, ogg, or flac — max 15MB"}}}},"application/json":{"schema":{"$ref":"#/components/schemas/SubmitTextAnswerInput"},"example":{"answer":"52"}}}},"responses":{"201":{"description":"Scored","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/EgmaResult"},"session":{"$ref":"#/components/schemas/EgmaSession"}}}}}},"400":{"description":"Validation failed, wrong input mode for this item's kind, the item already has a result, or the session is already completed\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"A concurrent submission already answered this item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The speech-to-text provider call failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The configured ASR provider is missing its credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/egma/content/egma-items":{"post":{"tags":["EGMA Content"],"summary":"Add a discrete EGMA item (quantity discrimination / missing number)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEgmaItemInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EgmaItem"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["EGMA Content"],"summary":"List discrete EGMA items","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"},{"name":"subtaskType","in":"query","schema":{"$ref":"#/components/schemas/DiscreteEgmaType"}},{"name":"language","in":"query","schema":{"$ref":"#/components/schemas/ReadingSubject"}}],"responses":{"200":{"description":"Paginated list of EGMA items","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EgmaItem"}}}}]}}}}}}},"/api/egma/content/arithmetic-fluency-items":{"post":{"tags":["EGMA Content"],"summary":"Add an arithmetic-fluency problem set","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArithmeticFluencyItemInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArithmeticFluencyItem"}}}},"400":{"$ref":"#/components/responses/ValidationError"}}},"get":{"tags":["EGMA Content"],"summary":"List arithmetic-fluency item sets","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"Paginated list of arithmetic-fluency item sets","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedEnvelope"},{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ArithmeticFluencyItem"}}}}]}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An API key from /dashboard (starts with `bk_`)."}},"parameters":{"SessionId":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PageSize":{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"Request failed schema validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{}}},"PaginatedEnvelope":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"Subject":{"type":"string","enum":["HINDI_READING","ENGLISH_READING","MATH"]},"ReadingSubject":{"type":"string","enum":["HINDI_READING","ENGLISH_READING"]},"SessionStatus":{"type":"string","enum":["IN_PROGRESS","COMPLETED"]},"InputMode":{"type":"string","enum":["VOICE","TEXT"]},"SubmitTextAnswerInput":{"type":"object","required":["answer"],"properties":{"answer":{"type":"string","description":"A whole number as a string for MATH/EGMA items; free text for comprehension questions.\n"}}},"ReadingLevel":{"type":"string","description":"Low to high. LEVEL_0: cannot recognise letters. LEVEL_1: can read letters. LEVEL_2: can read words. LEVEL_3: can read a Std I level paragraph. LEVEL_4: can read a Std II level story. Same names as MathLevel, different meaning — fetch both with labels at runtime via GET /api/aser/reference/levels rather than hardcoding this list.\n","enum":["LEVEL_0","LEVEL_1","LEVEL_2","LEVEL_3","LEVEL_4"]},"MathLevel":{"type":"string","description":"Low to high. LEVEL_0: cannot recognise numbers. LEVEL_1: can recognise numbers 1-99. LEVEL_2: can do 2-digit subtraction without borrowing. LEVEL_3: can do 2-digit subtraction with borrowing. LEVEL_4: can do 3-digit by 1-digit division.\n","enum":["LEVEL_0","LEVEL_1","LEVEL_2","LEVEL_3","LEVEL_4"]},"CreateAserSessionInput":{"type":"object","required":["childId"],"properties":{"childId":{"type":"string","description":"Opaque identifier for the child","owned":"by the calling app"},"subjects":{"type":"array","minItems":1,"maxItems":3,"items":{"$ref":"#/components/schemas/Subject"},"description":"Which tracks to create for this session, e.g. [\"HINDI_READING\", \"MATH\"] to skip English entirely — useful for deployments in a single language, or that only need one subject. Defaults to all three when omitted.\n"},"hindiReadingStartLevel":{"allOf":[{"$ref":"#/components/schemas/ReadingLevel"}],"description":"LEVEL_0 is not a valid start level (see the ReadingLevel description) — only LEVEL_1-LEVEL_4. Rejected with 400 if HINDI_READING isn't in `subjects`.\n"},"englishReadingStartLevel":{"allOf":[{"$ref":"#/components/schemas/ReadingLevel"}],"description":"Same rules as hindiReadingStartLevel, for ENGLISH_READING."},"mathStartLevel":{"allOf":[{"$ref":"#/components/schemas/MathLevel"}],"description":"Same rules as hindiReadingStartLevel, for MATH. Starts the rating at that level's tier (LEVEL_1 400, LEVEL_2 1000, LEVEL_3 1300, LEVEL_4 1900). Can't be combined with mathStartRating.\n"},"mathStartRating":{"type":"integer","minimum":0,"maximum":3000,"description":"Where the Math rating starts — send the child's last `result.mathRating` to carry it over between assessments (Beacon keeps no child history). Defaults to 1000. Rejected with 400 if MATH isn't in `subjects`, or together with mathStartLevel.\n"}}},"AserItem":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["reading"]},"content":{"type":"string"}}},{"type":"object","properties":{"id":{"type":"string","description":"Generated question's id: <trackId>:<question number>"},"type":{"type":"string","enum":["math"]},"prompt":{"type":"string","description":"Symbols only, e.g. \"52 - 27 = ?\", or \"47\" for number recognition","example":"52 - 27 = ?"},"difficulty":{"type":"integer","description":"The question tier's difficulty — 400 1-digit number, 550 1-digit addition, 700 2-digit number, 850 1-digit subtraction, 1000 subtraction without borrowing, 1300 with borrowing, 1600 2-digit ÷ 1-digit, 1900 3-digit ÷ 1-digit.\n"}}}]},"AserTrack":{"type":"object","properties":{"subject":{"$ref":"#/components/schemas/Subject"},"status":{"$ref":"#/components/schemas/SessionStatus"},"currentLevel":{"type":"string","description":"Present while status is IN_PROGRESS"},"finalLevel":{"type":"string","nullable":true},"rating":{"type":"integer","nullable":true,"description":"MATH only — the child's current (or, once completed, final) rating. currentLevel/finalLevel are derived from it."},"currentItem":{"allOf":[{"$ref":"#/components/schemas/AserItem"}],"nullable":true}}},"Attempt":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subject":{"$ref":"#/components/schemas/Subject"},"levelAttempted":{"type":"string"},"inputMode":{"$ref":"#/components/schemas/InputMode"},"transcript":{"type":"string","nullable":true},"transcriptionProvider":{"type":"string","nullable":true,"example":"openai"},"answerText":{"type":"string","nullable":true},"score":{"type":"number","description":"0-1 for reading (word-overlap accuracy); 0 or 1 for math (exact match)"},"passed":{"type":"boolean"},"prompt":{"type":"string","nullable":true,"description":"MATH only — the question that was asked"},"difficulty":{"type":"integer","nullable":true,"description":"MATH only — that question's tier difficulty"},"ratingAfter":{"type":"integer","nullable":true,"description":"MATH only — the child's rating after this answer"},"createdAt":{"type":"string","format":"date-time"}}},"AserSessionResult":{"type":"object","nullable":true,"properties":{"hindiReadingLevel":{"$ref":"#/components/schemas/ReadingLevel"},"englishReadingLevel":{"$ref":"#/components/schemas/ReadingLevel"},"mathLevel":{"$ref":"#/components/schemas/MathLevel"},"mathRating":{"type":"integer","nullable":true,"description":"The Math track's final rating; mathLevel is derived from it (below 400 LEVEL_0, 400 LEVEL_1, 1000 LEVEL_2, 1300 LEVEL_3, 1900 LEVEL_4). Send it back as mathStartRating next time to carry it over.\n"}}},"AserSession":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"childId":{"type":"string"},"status":{"$ref":"#/components/schemas/SessionStatus"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"result":{"$ref":"#/components/schemas/AserSessionResult"},"tracks":{"type":"array","items":{"$ref":"#/components/schemas/AserTrack"}}}},"AserSessionWithHistory":{"allOf":[{"$ref":"#/components/schemas/AserSession"},{"type":"object","properties":{"tracks":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AserTrack"},{"type":"object","properties":{"attempts":{"type":"array","items":{"$ref":"#/components/schemas/Attempt"}}}}]}}}}]},"ReadingItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subject":{"$ref":"#/components/schemas/ReadingSubject"},"level":{"$ref":"#/components/schemas/ReadingLevel"},"content":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CreateReadingItemInput":{"type":"object","required":["subject","level","content"],"properties":{"subject":{"$ref":"#/components/schemas/ReadingSubject"},"level":{"$ref":"#/components/schemas/ReadingLevel"},"content":{"type":"string","minLength":1,"maxLength":5000}}},"MathItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"level":{"$ref":"#/components/schemas/MathLevel"},"prompt":{"type":"string"},"expectedAnswer":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CreateMathItemInput":{"type":"object","required":["level","prompt","expectedAnswer"],"properties":{"level":{"$ref":"#/components/schemas/MathLevel"},"prompt":{"type":"string","minLength":1,"maxLength":1000},"expectedAnswer":{"type":"string","pattern":"^\\d+$"}}},"ReferenceLevels":{"type":"object","properties":{"reading":{"type":"array","items":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/ReadingLevel"},"label":{"type":"string"}}}},"math":{"type":"array","items":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/MathLevel"},"label":{"type":"string"}}}}}},"FluencySubtaskType":{"type":"string","enum":["LETTER_NAMING","NONSENSE_WORD","ORAL_READING","LISTENING_PASSAGE"]},"EgraItemKind":{"type":"string","enum":["LETTER_NAMING_FLUENCY","NONSENSE_WORD_FLUENCY","ORAL_READING_FLUENCY","READING_COMPREHENSION_QUESTION","LISTENING_PASSAGE","LISTENING_COMPREHENSION_QUESTION"]},"CreateEgraSessionInput":{"type":"object","required":["childId","language"],"properties":{"childId":{"type":"string","description":"Opaque identifier for the child","owned":"by the calling app"},"language":{"allOf":[{"$ref":"#/components/schemas/ReadingSubject"}],"description":"Real EGRA instruments are normed per-language; a session covers one, not both like ASER."}}},"FluencyItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subtaskType":{"$ref":"#/components/schemas/FluencySubtaskType"},"language":{"$ref":"#/components/schemas/ReadingSubject"},"content":{"type":"string","description":"Space-separated letters/words for LETTER_NAMING/NONSENSE_WORD; full text for ORAL_READING/LISTENING_PASSAGE"},"createdAt":{"type":"string","format":"date-time"}}},"CreateFluencyItemInput":{"type":"object","required":["subtaskType","language","content"],"properties":{"subtaskType":{"$ref":"#/components/schemas/FluencySubtaskType"},"language":{"$ref":"#/components/schemas/ReadingSubject"},"content":{"type":"string","minLength":1,"maxLength":10000}}},"ComprehensionQuestion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fluencyItemId":{"type":"string","format":"uuid"},"question":{"type":"string"},"expectedAnswerKeywords":{"type":"string","description":"Comma-separated acceptable keywords/phrases"},"order":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}}},"CreateComprehensionQuestionInput":{"type":"object","required":["fluencyItemId","question","expectedAnswerKeywords"],"properties":{"fluencyItemId":{"type":"string","format":"uuid"},"question":{"type":"string","minLength":1,"maxLength":500},"expectedAnswerKeywords":{"type":"string","minLength":1,"maxLength":500},"order":{"type":"integer","minimum":0,"default":0}}},"EgraItemPrompt":{"type":"object","description":"Exactly one of these fields is present, depending on the item's kind","properties":{"content":{"type":"string","description":"LETTER_NAMING/NONSENSE_WORD/ORAL_READING/LISTENING_PASSAGE"},"question":{"type":"string","description":"READING/LISTENING_COMPREHENSION_QUESTION"}}},"EgraResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"inputMode":{"$ref":"#/components/schemas/InputMode"},"transcript":{"type":"string","nullable":true},"transcriptionProvider":{"type":"string","nullable":true},"answerText":{"type":"string","nullable":true},"correctCount":{"type":"integer","nullable":true,"description":"Fluency kinds only"},"attemptedCount":{"type":"integer","nullable":true,"description":"Fluency kinds only"},"durationSeconds":{"type":"number","nullable":true,"description":"Fluency kinds only. Also null (not 0) when the uploaded audio's duration couldn't be determined (e.g. an unfinalized/streamed container with no duration header) — a real 0-second recording is not something this can distinguish from that case either way, so both read as null rather than a possibly-misleading 0.\n"},"ratePerMinute":{"type":"number","nullable":true,"description":"Fluency kinds only; null whenever durationSeconds is null."},"score":{"type":"number","nullable":true,"description":"1/0 for comprehension (never null); mirrors ratePerMinute for fluency kinds (so also null when duration is unknown)"},"passed":{"type":"boolean","nullable":true,"description":"Right/wrong for comprehension; null for fluency kinds (they report a rate, not pass/fail)"},"createdAt":{"type":"string","format":"date-time"}}},"EgraSessionItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/EgraItemKind"},"order":{"type":"integer"},"requiresAttempt":{"type":"boolean","description":"false only for LISTENING_PASSAGE"},"allowedInputModes":{"type":"array","items":{"$ref":"#/components/schemas/InputMode"}},"prompt":{"$ref":"#/components/schemas/EgraItemPrompt"},"result":{"allOf":[{"$ref":"#/components/schemas/EgraResult"}],"nullable":true}}},"EgraResultSummary":{"type":"object","nullable":true,"description":"null until every attemptable item has a result","properties":{"letterNamingFluency":{"$ref":"#/components/schemas/FluencySummary"},"nonsenseWordFluency":{"$ref":"#/components/schemas/FluencySummary"},"oralReadingFluency":{"$ref":"#/components/schemas/FluencySummary"},"readingComprehensionAccuracy":{"type":"number","nullable":true,"description":"0-1"},"listeningComprehensionAccuracy":{"type":"number","nullable":true,"description":"0-1"}}},"FluencySummary":{"type":"object","nullable":true,"properties":{"correctCount":{"type":"integer"},"attemptedCount":{"type":"integer"},"durationSeconds":{"type":"number"},"ratePerMinute":{"type":"number"}}},"EgraSession":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"childId":{"type":"string"},"language":{"$ref":"#/components/schemas/ReadingSubject"},"status":{"$ref":"#/components/schemas/SessionStatus"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"result":{"$ref":"#/components/schemas/EgraResultSummary"},"items":{"type":"array","items":{"$ref":"#/components/schemas/EgraSessionItem"}}}},"DiscreteEgmaType":{"type":"string","enum":["QUANTITY_DISCRIMINATION","MISSING_NUMBER"]},"EgmaItemKind":{"type":"string","enum":["QUANTITY_DISCRIMINATION","MISSING_NUMBER","ARITHMETIC_FLUENCY"]},"CreateEgmaSessionInput":{"type":"object","required":["childId","language"],"properties":{"childId":{"type":"string","description":"Opaque identifier for the child","owned":"by the calling app"},"language":{"allOf":[{"$ref":"#/components/schemas/ReadingSubject"}],"description":"The discrete items' instructional text is language-specific, so — like EGRA — a session covers one language.\n"}}},"EgmaItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subtaskType":{"$ref":"#/components/schemas/DiscreteEgmaType"},"language":{"allOf":[{"$ref":"#/components/schemas/ReadingSubject"}],"description":"The prompt's instructional text (\"Which is bigger...\") is language-specific."},"prompt":{"type":"string"},"expectedAnswer":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CreateEgmaItemInput":{"type":"object","required":["subtaskType","language","prompt","expectedAnswer"],"properties":{"subtaskType":{"$ref":"#/components/schemas/DiscreteEgmaType"},"language":{"$ref":"#/components/schemas/ReadingSubject"},"prompt":{"type":"string","minLength":1,"maxLength":500},"expectedAnswer":{"type":"string","pattern":"^\\d+$"}}},"ArithmeticFluencyItem":{"type":"object","description":"Language-agnostic (numbers only), unlike EgmaItem's discrete prompts.","properties":{"id":{"type":"string","format":"uuid"},"content":{"type":"string","description":"\"|\"-separated problems, e.g. \"9+6|7-2|4x8\""},"expectedAnswers":{"type":"string","description":"\"|\"-separated answers, same order/count as content's problems"},"createdAt":{"type":"string","format":"date-time"}}},"CreateArithmeticFluencyItemInput":{"type":"object","required":["content","expectedAnswers"],"properties":{"content":{"type":"string","minLength":1,"maxLength":10000},"expectedAnswers":{"type":"string","minLength":1,"maxLength":2000}}},"EgmaItemPrompt":{"type":"object","description":"Exactly one of these fields is present, depending on the item's kind","properties":{"prompt":{"type":"string","description":"QUANTITY_DISCRIMINATION/MISSING_NUMBER"},"problems":{"type":"array","items":{"type":"string"},"description":"ARITHMETIC_FLUENCY"}}},"EgmaResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"inputMode":{"$ref":"#/components/schemas/InputMode"},"transcript":{"type":"string","nullable":true},"transcriptionProvider":{"type":"string","nullable":true},"answerText":{"type":"string","nullable":true},"correctCount":{"type":"integer","nullable":true,"description":"ARITHMETIC_FLUENCY only"},"attemptedCount":{"type":"integer","nullable":true,"description":"ARITHMETIC_FLUENCY only"},"durationSeconds":{"type":"number","nullable":true,"description":"ARITHMETIC_FLUENCY only. Also null (not 0) when the uploaded audio's duration couldn't be determined, same reasoning as EgraResult.durationSeconds.\n"},"ratePerMinute":{"type":"number","nullable":true,"description":"ARITHMETIC_FLUENCY only; null whenever durationSeconds is null."},"score":{"type":"number","nullable":true,"description":"1/0 for discrete items (never null); mirrors ratePerMinute for ARITHMETIC_FLUENCY (so also null when duration is unknown)"},"passed":{"type":"boolean","nullable":true,"description":"Right/wrong for discrete items; null for ARITHMETIC_FLUENCY (reports a rate, not pass/fail)"},"createdAt":{"type":"string","format":"date-time"}}},"EgmaSessionItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/EgmaItemKind"},"order":{"type":"integer"},"requiresAttempt":{"type":"boolean","description":"Always true — EGMA has no display-only item like EGRA's LISTENING_PASSAGE"},"allowedInputModes":{"type":"array","items":{"$ref":"#/components/schemas/InputMode"}},"prompt":{"$ref":"#/components/schemas/EgmaItemPrompt"},"result":{"allOf":[{"$ref":"#/components/schemas/EgmaResult"}],"nullable":true}}},"EgmaResultSummary":{"type":"object","nullable":true,"description":"null until every item has a result","properties":{"quantityDiscriminationAccuracy":{"type":"number","nullable":true,"description":"0-1"},"missingNumberAccuracy":{"type":"number","nullable":true,"description":"0-1"},"arithmeticFluency":{"$ref":"#/components/schemas/FluencySummary"}}},"EgmaSession":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"childId":{"type":"string"},"language":{"$ref":"#/components/schemas/ReadingSubject"},"status":{"$ref":"#/components/schemas/SessionStatus"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"result":{"$ref":"#/components/schemas/EgmaResultSummary"},"items":{"type":"array","items":{"$ref":"#/components/schemas/EgmaSessionItem"}}}}}}}