{ "openapi": "3.1.0", "info": { "title": "TubeQuest Parent API", "version": "1.10.0", "description": "Family-scoped read/write integration API. Generate a key in the native app under Settings → Integrations → External API key. Historical answer coverage is explicit: legacySnapshot rows contain only the last previously stored answer. Never embed family keys in public JavaScript. External API keys default to 100 requests per parent per UTC day. Team admins can change individual allowances. GET /api-usage is unmetered. App/browser session routes are outside this quota. Family account levels are Free, Paid and Paid Premium. IEP processing and adoption require Paid Premium. Levels are assigned by team admins; billing is not connected." }, "servers": [ { "url": "/api/v1", "description": "The same server as the TubeQuest app" } ], "security": [ { "ParentApiKey": [] } ], "paths": { "/children": { "get": { "summary": "List your children", "operationId": "get_children", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Child" } } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } } }, "post": { "summary": "Create a child and copy grade templates", "operationId": "post_children", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Child" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 80 }, "grade": { "enum": [ "kindergarten", "grade1", "grade2", "grade3", "grade4", "grade5", "grade6", "grade7" ] }, "contentFilterLevel": { "enum": [ "kids", "strict", "moderate", "unrestricted" ], "description": "YouTube filtering mode. Family video, channel and keyword blocks always apply. Missing/unknown stored settings use kids.", "default": "kids" }, "voiceSearchEnabled": { "type": [ "boolean", "null" ], "description": "Child voice-search override. null (or omitted on create) follows the grade: enabled for kindergarten and grade1, disabled for grades2–7. true/false persists across grade changes. PATCH null restores automatic defaults." }, "mathQuestionInterval": { "type": "integer", "minimum": 1, "maximum": 100, "default": 3, "description": "Videos between math/reading questions for this child only, including replays. New children default to 3. Existing children retain their former family frequency on migration. Changes do not reset question banks or activity." }, "challengeSuccessMessage": { "type": "string", "minLength": 1, "maxLength": 160, "default": "That is correct!", "description": "Custom notice shown for one second after a correct math or reading answer." }, "challengeSuccessAudioEnabled": { "type": "boolean", "default": true, "description": "Play bundled encouragement, rotating Great job!, Excellent!, Good answer! on each device for this child." } }, "required": [ "firstName", "grade" ], "additionalProperties": false } } } } } }, "/children/{childId}": { "get": { "summary": "Get your child profile", "operationId": "get_children_childId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Child" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "patch": { "summary": "Update child profile (grade changes replace both banks)", "operationId": "patch_children_childId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Child" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "maxLength": 80 }, "grade": { "enum": [ "kindergarten", "grade1", "grade2", "grade3", "grade4", "grade5", "grade6", "grade7" ] }, "contentFilterLevel": { "enum": [ "kids", "strict", "moderate", "unrestricted" ], "description": "YouTube filtering mode. Family video, channel and keyword blocks always apply. Missing/unknown stored settings use kids." }, "voiceSearchEnabled": { "type": [ "boolean", "null" ], "description": "Child voice-search override. null (or omitted on create) follows the grade: enabled for kindergarten and grade1, disabled for grades2–7. true/false persists across grade changes. PATCH null restores automatic defaults." }, "mathQuestionInterval": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Videos between math/reading questions for this child only, including replays. New children default to 3. Existing children retain their former family frequency on migration. Changes do not reset question banks or activity. Omitting this field preserves the current choice." }, "challengeSuccessMessage": { "type": "string", "minLength": 1, "maxLength": 160, "default": "That is correct!", "description": "Custom notice shown for one second after a correct math or reading answer." }, "challengeSuccessAudioEnabled": { "type": "boolean", "default": true, "description": "Play bundled encouragement, rotating Great job!, Excellent!, Good answer! on each device for this child." } }, "additionalProperties": false } } } } } }, "/children/{childId}/activity": { "get": { "summary": "Read the child activity timeline", "operationId": "get_children_childId_activity", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivityPage" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum items per page." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "description": "Use the previous nextOffset." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower timestamp." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive upper timestamp. Use a fixed timestamp across export pages." }, { "name": "type", "in": "query", "required": false, "schema": { "enum": [ "video_opened", "video_completed", "question_asked", "answer_submitted", "video_search", "message_sent", "child_opened", "child_updated", "questions_reset", "questions_edited", "iep_generation_requested", "iep_generated", "iep_generation_failed", "iep_question_adopted", "iep_section_adopted", "iep_program_cleared", "iep_plan_deleted" ] }, "description": "Filter event type." } ], "description": "Newest first. Includes recorded activity only; no playback positions, replay events, or time-on-task estimates." } }, "/children/{childId}/watch-history": { "get": { "summary": "Read video metadata and completion records", "operationId": "get_children_childId_watch_history", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WatchPage" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum items per page." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "description": "Use the previous nextOffset." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower timestamp." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive upper timestamp. Use a fixed timestamp across export pages." } ] } }, "/children/{childId}/questions": { "get": { "summary": "Read issued math and reading questions", "operationId": "get_children_childId_questions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionPage" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum items per page." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "description": "Use the previous nextOffset." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower timestamp." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive upper timestamp. Use a fixed timestamp across export pages." }, { "name": "subject", "in": "query", "required": false, "schema": { "enum": [ "math", "reading" ] }, "description": "Question subject." }, { "name": "status", "in": "query", "required": false, "schema": { "enum": [ "unanswered", "correct", "incorrect" ] }, "description": "Latest outcome." } ], "description": "Newest first, filtered by askedAt. Bank entries and issued questions have different IDs. Edits never rewrite these historical snapshots." } }, "/children/{childId}/questions/{subject}/{questionId}": { "get": { "summary": "Read one issued question", "operationId": "get_children_childId_questions_subject_questionId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Question" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subject", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "math", "reading" ] } }, { "name": "questionId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/children/{childId}/questions/{subject}/{questionId}/attempts": { "get": { "summary": "Read recorded answers to a question", "operationId": "get_children_childId_questions_subject_questionId_attempts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttemptPage" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subject", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "math", "reading" ] } }, { "name": "questionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Maximum items per page." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 10000000, "default": 0 }, "description": "Use the previous nextOffset." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower timestamp." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Exclusive upper timestamp. Use a fixed timestamp across export pages." } ], "description": "Oldest first. Legacy snapshots contain only the last saved answer; earlier overwritten attempts are unavailable." } }, "/children/{childId}/math-questions": { "get": { "summary": "List reusable math-questions", "operationId": "get_children_childId_math_questions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MathBankEntry" } } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Add reusable math-questions", "operationId": "post_children_childId_math_questions", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MathBankEntry" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000 }, "correctAnswer": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Valid whole number, decimal, fraction, or mixed number." } }, "required": [ "question", "correctAnswer" ], "additionalProperties": false } } } } } }, "/children/{childId}/math-questions/{bankId}": { "patch": { "summary": "Edit reusable math-questions", "operationId": "patch_children_childId_math_questions_bankId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MathBankEntry" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bankId", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Affects future questions only. Reading edits clear obsolete audio. Ownership and grade metadata cannot be supplied.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 2000 }, "correctAnswer": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "Valid whole number, decimal, fraction, or mixed number." } }, "additionalProperties": false } } } } }, "delete": { "summary": "Remove reusable math-questions", "operationId": "delete_children_childId_math_questions_bankId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bankId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/children/{childId}/reading-words": { "get": { "summary": "List reusable reading-words", "operationId": "get_children_childId_reading_words", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ReadingBankEntry" } } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Add reusable reading-words", "operationId": "post_children_childId_reading_words", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadingBankEntry" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "word": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "word" ], "additionalProperties": false } } } } } }, "/children/{childId}/reading-words/{bankId}": { "patch": { "summary": "Edit reusable reading-words", "operationId": "patch_children_childId_reading_words_bankId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadingBankEntry" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bankId", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Affects future questions only. Reading edits clear obsolete audio. Ownership and grade metadata cannot be supplied.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "word": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "word" ], "additionalProperties": false } } } } }, "delete": { "summary": "Remove reusable reading-words", "operationId": "delete_children_childId_reading_words_bankId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bankId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/children/{childId}/reading-words/{bankId}/audio": { "post": { "summary": "Generate reading audio when configured", "operationId": "post_children_childId_reading_words_bankId_audio", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadingBankEntry" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bankId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/children/{childId}/reset-questions": { "post": { "summary": "Replace both banks from the current grade templates", "operationId": "post_children_childId_reset_questions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "description": "Removes custom bank content. Preserves all issued questions and answer history." } }, "/settings": { "get": { "summary": "Read archived family quiz frequency", "operationId": "get_settings", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Duplicate reading word", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "deprecated": true, "description": "Quiz frequency is now a child profile field. Use GET /children/{childId} and PATCH /children/{childId} with mathQuestionInterval. This legacy GET returns the archived family setting and does not describe current child frequencies. PATCH returns 409 and never changes child settings." }, "patch": { "summary": "Retired family quiz-frequency setter", "operationId": "patch_settings", "responses": { "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, or revoked API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Wrong role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource does not exist or does not belong to this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Frequency must be edited on the individual child profile; no settings changed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mathQuestionInterval": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "mathQuestionInterval" ], "additionalProperties": false } } } }, "deprecated": true, "description": "Quiz frequency is now a child profile field. Use GET /children/{childId} and PATCH /children/{childId} with mathQuestionInterval. This legacy GET returns the archived family setting and does not describe current child frequencies. PATCH returns 409 and never changes child settings." } }, "/children/{childId}/progress": { "get": { "summary": "Daily learning metrics and comparison", "operationId": "get__children_childId_progress", "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "through", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "timeZone", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC", "description": "IANA time zone. Dates are inclusive; default last seven local calendar days. Maximum 90 days, ending no later than today." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningProgress" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing or not owned by this parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Request ID or decision conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "422": { "description": "Too much activity; shorten the range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted, or a new report request for this child was already accepted on this calendar date. Report failures count. Saved reports and decisions remain available within the external API allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/APIQuotaExceeded" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/children/{childId}/reports": { "get": { "summary": "Latest 50 report snapshots", "operationId": "get__children_childId_reports", "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LearningReportSummary" } } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing or not owned by this parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Request ID or decision conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "422": { "description": "Too much activity; shorten the range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted, or a new report request for this child was already accepted on this calendar date. Report failures count. Saved reports and decisions remain available within the external API allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/APIQuotaExceeded" }, { "$ref": "#/components/schemas/Error" } ] } } } } } }, "post": { "summary": "Generate an AI learning report", "operationId": "post__children_childId_reports", "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningReport" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing or not owned by this parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Request ID or decision conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "422": { "description": "Too much activity; shorten the range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted, or a new report request for this child was already accepted on this calendar date. Report failures count. Saved reports and decisions remain available within the external API allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/APIQuotaExceeded" }, { "$ref": "#/components/schemas/Error" } ] } } } }, "202": { "description": "Existing generation is pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningReport" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "from": { "type": "string", "format": "date" }, "through": { "type": "string", "format": "date" }, "timeZone": { "type": "string", "default": "UTC", "description": "IANA time zone. Dates are inclusive; default last seven local calendar days. Maximum 90 days, ending no later than today." } }, "required": [ "id" ], "additionalProperties": false } } } }, "description": "May take about a minute. Reuse the same UUID and range on retries. 202 means an existing generation is pending; poll GET until ready or failed. Failed IDs are not regenerated. Nothing is applied automatically. One accepted attempt per child per server calendar day, including failures. Reuse the same UUID to retrieve that request without another generation. Missing provider configuration produces a saved failed report with a generic parent-facing message. GET /children/{childId}/reports/allowance returns the next midnight reset." } }, "/children/{childId}/reports/{reportId}": { "get": { "summary": "Read a saved report and current decisions", "operationId": "get__children_childId_reports_reportId", "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningReport" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing or not owned by this parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Request ID or decision conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "422": { "description": "Too much activity; shorten the range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted, or a new report request for this child was already accepted on this calendar date. Report failures count. Saved reports and decisions remain available within the external API allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/APIQuotaExceeded" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/children/{childId}/reports/{reportId}/view": { "post": { "summary": "Record an explicit report view", "operationId": "post__children_childId_reports_reportId_view", "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing or not owned by this parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Request ID or decision conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "422": { "description": "Too much activity; shorten the range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted, or a new report request for this child was already accepted on this calendar date. Report failures count. Saved reports and decisions remain available within the external API allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/APIQuotaExceeded" }, { "$ref": "#/components/schemas/Error" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false } } } }, "description": "Use a new event UUID for each view; reuse it only on retries. Polling does not record views." } }, "/children/{childId}/reports/{reportId}/suggestions/{suggestionId}/decision": { "post": { "summary": "Review and optionally apply one suggestion", "operationId": "post__children_childId_reports_reportId_suggestions_suggestionId_decision", "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "reportId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "suggestionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningReport" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing or not owned by this parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Request ID or decision conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "422": { "description": "Too much activity; shorten the range", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted, or a new report request for this child was already accepted on this calendar date. Report failures count. Saved reports and decisions remain available within the external API allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/APIQuotaExceeded" }, { "$ref": "#/components/schemas/Error" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] } }, "required": [ "decision" ], "additionalProperties": false } } } }, "description": "Approval and mutation are one transaction under the owning parent. Repeated same decision is idempotent. Stale proposals are recorded as stale without a bank change. Rejection never mutates questions." } }, "/community/blocks": { "get": { "summary": "Top ten community videos and channels not in your block lists", "operationId": "get_community_blocks", "description": "Separate lists ranked by distinct parent blockers, with stable alphabetical ties. Excludes your direct video and normalized channel blocks. Aggregates only: no identities, reasons or activity from other families. YouTube metadata is best effort. No query parameters.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityBlocks" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } } }, "post": { "summary": "Block an explicit selection for your family", "operationId": "post_community_blocks", "description": "Atomically adds the supplied videos and channels to your family blocks, retaining existing blocks and reasons. Targets must still exist in community or your own blocks. Records one usage event for actual additions. Retry the same UUID and targets to receive the original receipt, even if you subsequently unblock an item. GET again after success for the next suggestions.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityBlockSelection" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityBlockReceipt" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Stale/unknown community target, or request ID reused for another selection. Refresh before starting a new request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted. Retry after reset or ask a team admin to raise the allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaExceeded" } } } } } } }, "/api-usage": { "get": { "summary": "Read your daily external API allowance without consuming it", "operationId": "get_api_usage", "description": "Available even when the allowance is exhausted. Includes admitted requests and quota rejections for the current UTC day. No other parent can be selected. HEAD is also unmetered.", "responses": { "200": { "description": "Current allowance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/APIQuotaStatus" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/premium": { "get": { "summary": "Read your account level, IEP access and AI availability", "description": "Retained for older app versions. enabled is true only for Paid Premium; GET /account-plan exposes general account-level information.", "operationId": "get__premium", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PremiumAccess" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent or premium access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [] } }, "/children/{childId}/iep/extract": { "post": { "summary": "Extract an IEP document for private text review", "description": "Requires premium and child ownership before upload parsing. Maximum 10 MB, 100 PDF pages and 40,000 extracted characters. Original file is discarded; this does not invoke the LLM. Searchable PDF, DOCX or UTF-8 TXT; scanned PDFs need OCR first.", "operationId": "post__children_childId_iep_extract", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IEPExtractedText" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "413": { "description": "Document exceeds 10 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "415": { "description": "Use application/octet-stream", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "422": { "description": "Unreadable, scanned, oversized or timed-out document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "pdf", "docx", "txt" ] } } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/children/{childId}/iep/plans": { "get": { "summary": "List latest 50 saved IEP plan summaries", "description": "Owning parent may still read and delete plans after premium revocation.", "operationId": "get__children_childId_iep_plans", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IEPPlanSummary" } } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ] }, "post": { "summary": "Propose questions from reviewed IEP goals", "description": "Requires premium and explicit consent. Sends reviewed text and grade to configured OpenRouter model. Up to three new requests per family per rolling 24 hours, including failed/deleted attempts. Reuse UUID with identical text for safe retries. Returns failed status on invalid/provider failure; never edits banks. Raw input is discarded after processing. Up to six questions per relevant section; unsupported sections may be omitted.", "operationId": "post__children_childId_iep_plans", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IEPPlan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "202": { "description": "A request with this UUID is already pending; poll the plan GET endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IEPPlan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "text": { "type": "string", "minLength": 30, "maxLength": 12000 }, "consent": { "const": true } }, "required": [ "id", "text", "consent" ] } } } } } }, "/children/{childId}/iep/plans/{planId}": { "get": { "summary": "Read a saved IEP plan and adoption receipts", "description": "", "operationId": "get__children_childId_iep_plans_planId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IEPPlan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "summary": "Delete a saved IEP plan", "description": "Owned plans may be deleted after premium revocation. Keeps adopted bank questions and history. Also prevents an in-flight provider response from recreating the plan.", "operationId": "delete__children_childId_iep_plans_planId", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/children/{childId}/iep/plans/{planId}/adopt": { "post": { "summary": "Adopt one question or all remaining questions in a section", "description": "Requires premium, a ready plan and unchanged child grade. Atomic under a child lock. Already adopted entries are skipped on all retries, even if later removed/reset. Adds to the existing bank; use explicit clear separately to replace it.", "operationId": "post__children_childId_iep_plans_planId_adopt", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IEPPlan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "questionId": { "type": "string", "format": "uuid" } }, "required": [ "questionId" ] }, { "type": "object", "additionalProperties": false, "properties": { "section": { "type": "string", "enum": [ "math", "geometry", "algebra", "reading" ] } }, "required": [ "section" ] } ] } } } } } }, "/children/{childId}/iep/program": { "get": { "summary": "Review bank counts and revision before clearing", "description": "", "operationId": "get__children_childId_iep_program", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IEPProgram" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ] } }, "/children/{childId}/iep/program/clear": { "post": { "summary": "Clear this child’s math and reading question banks", "description": "Requires premium and a current program revision. Stale revisions return 409. Retry with the same UUID/revision returns the original removed counts and never clears later additions. Issued questions, answers, watch history and profile settings are preserved. Adopt new practice afterward.", "operationId": "post__children_childId_iep_program_clear", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IEPCleared" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required; IEP uploads, generation, adoption and clearing additionally require Paid Premium", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "404": { "description": "Child or plan not in this family", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "409": { "description": "Stale program/grade or conflicting retry key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API, generation or extraction concurrency limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "503": { "description": "Provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirmation": { "const": "CLEAR" } }, "required": [ "id", "revision", "confirmation" ] } } } } } }, "/account-plan": { "get": { "summary": "Read your family’s account level and feature access", "description": "Read-only. Returns only the authenticated parent’s family. Parents and external API keys cannot change tiers. Counts toward the normal daily external API allowance.", "operationId": "get_account_plan", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPlan" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Parent authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "403": { "description": "Parent access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily API allowance reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } } }, "parameters": [] } }, "/children/{childId}/reports/allowance": { "get": { "summary": "Read this child’s daily learning-report allowance", "operationId": "get_child_report_allowance", "parameters": [ { "name": "childId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningReportAllowance" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing or invalid parent credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Parent role required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource missing or not owned by this parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } } } }, "429": { "description": "Daily external API allowance exhausted, or a new report request for this child was already accepted on this calendar date. Report failures count. Saved reports and decisions remain available within the external API allowance.", "headers": { "X-RateLimit-Limit": { "description": "Effective daily request allowance for this parent.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Remaining admitted requests in the UTC day, after this request.", "schema": { "type": "integer", "minimum": 0 } }, "X-RateLimit-Reset": { "description": "Next midnight UTC as Unix seconds.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds until the daily quota resets; present for API_DAILY_LIMIT_REACHED.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/APIQuotaExceeded" }, { "$ref": "#/components/schemas/Error" } ] } } } } }, "description": "One report attempt per child per calendar date in the server-controlled REPORT_TIME_ZONE (UTC by default). All accepted attempts count, including missing configuration and provider failures. Chart date ranges, device timezone, grade changes and sign-in do not reset the allowance. Saved reports remain readable." } } }, "components": { "securitySchemes": { "ParentApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "Child": { "type": "object", "properties": { "id": { "type": "string" }, "firstName": { "type": [ "string", "null" ] }, "role": { "const": "child" }, "parentId": { "type": "string" }, "grade": { "type": "string" }, "contentFilterLevel": { "type": "string" }, "videosWatchedCount": { "type": [ "integer", "null" ] }, "mathQuestionsAnswered": { "type": [ "integer", "null" ] }, "voiceSearchEnabled": { "type": [ "boolean", "null" ], "description": "Child voice-search override. null (or omitted on create) follows the grade: enabled for kindergarten and grade1, disabled for grades2–7. true/false persists across grade changes. PATCH null restores automatic defaults." }, "mathQuestionInterval": { "type": "integer", "minimum": 1, "maximum": 100, "default": 3, "description": "Videos between math/reading questions for this child only, including replays. New children default to 3. Existing children retain their former family frequency on migration. Changes do not reset question banks or activity." }, "challengeSuccessMessage": { "type": "string", "minLength": 1, "maxLength": 160, "default": "That is correct!", "description": "Custom notice shown for one second after a correct math or reading answer." }, "challengeSuccessAudioEnabled": { "type": "boolean", "default": true, "description": "Play bundled encouragement, rotating Great job!, Excellent!, Good answer! on each device for this child." } } }, "Attempt": { "type": "object", "properties": { "id": { "type": "string" }, "answer": { "type": [ "string", "null" ] }, "isCorrect": { "type": [ "boolean", "null" ] }, "answeredAt": { "type": "string", "format": "date-time" }, "legacySnapshot": { "type": "boolean" } }, "required": [ "id", "answer", "isCorrect", "answeredAt", "legacySnapshot" ] }, "Question": { "type": "object", "properties": { "id": { "type": "string" }, "childId": { "type": "string" }, "subject": { "enum": [ "math", "reading" ] }, "bankQuestionId": { "type": [ "string", "null" ] }, "bankQuestionExists": { "type": [ "boolean", "null" ] }, "prompt": { "type": "string" }, "correctAnswer": { "type": "string" }, "word": { "type": [ "string", "null" ] }, "choices": { "type": [ "array", "null" ], "items": { "type": "string" } }, "audioUrl": { "type": [ "string", "null" ] }, "grade": { "type": "string" }, "askedAt": { "type": [ "string", "null" ], "format": "date-time" }, "latestAnswer": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "answer": { "type": [ "string", "null" ] }, "isCorrect": { "type": [ "boolean", "null" ] }, "answeredAt": { "type": "string", "format": "date-time" } } } ] }, "reportedAttemptCount": { "type": [ "integer", "null" ] }, "recordedAttemptCount": { "type": "integer" }, "attemptHistoryComplete": { "type": "boolean" } } }, "Activity": { "type": "object", "properties": { "id": { "type": "string" }, "childId": { "type": "string" }, "actorId": { "type": "string" }, "type": { "type": "string" }, "occurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "details": { "type": "object", "description": "Event-specific video metadata, question snapshot, answer/result, bounded search term, or child-related action. Answer events include legacySnapshot." } }, "required": [ "id", "childId", "actorId", "type", "occurredAt", "details" ] }, "Watch": { "type": "object", "properties": { "id": { "type": "string" }, "childId": { "type": "string" }, "videoId": { "type": "string" }, "title": { "type": "string" }, "thumbnail": { "type": [ "string", "null" ] }, "channelName": { "type": [ "string", "null" ] }, "duration": { "type": [ "string", "null" ] }, "searchTerm": { "type": [ "string", "null" ] }, "openedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completed": { "type": [ "boolean", "null" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "clientReportedQuizCorrect": { "type": [ "boolean", "null" ] } } }, "MathBankEntry": { "type": "object", "properties": { "id": { "type": "string" }, "childId": { "type": "string" }, "question": { "type": "string" }, "correctAnswer": { "type": "string" }, "difficulty": { "type": "string" }, "standard": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "explanation": { "type": [ "string", "null" ] } } }, "ReadingBankEntry": { "type": "object", "properties": { "id": { "type": "string" }, "childId": { "type": "string" }, "word": { "type": "string" }, "difficulty": { "type": "string" }, "audioUrl": { "type": [ "string", "null" ] }, "questionText": { "type": [ "string", "null" ] }, "passage": { "type": [ "string", "null" ] }, "answerChoices": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "description": "Listening word or IEP comprehension entry. For comprehension, questionText/passage/answerChoices are present and word is the correct answer for the parent. Single-word PATCH/audio generation is not supported for comprehension; DELETE is supported." }, "Settings": { "type": "object", "properties": { "mathQuestionInterval": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "mathQuestionInterval" ] }, "Message": { "type": "object", "properties": { "message": { "type": "string" } } }, "AttemptPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Attempt" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "limit", "offset", "nextOffset" ] }, "QuestionPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Question" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "limit", "offset", "nextOffset" ] }, "ActivityPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Activity" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "limit", "offset", "nextOffset" ] }, "WatchPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Watch" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] } }, "required": [ "items", "total", "limit", "offset", "nextOffset" ] }, "LearningRange": { "type": "object", "properties": { "from": { "type": "string", "format": "date" }, "through": { "type": "string", "format": "date" }, "timeZone": { "type": "string", "default": "UTC", "description": "IANA time zone. Dates are inclusive; default last seven local calendar days. Maximum 90 days, ending no later than today." }, "days": { "type": "integer" }, "previousFrom": { "type": "string", "format": "date" }, "previousThrough": { "type": "string", "format": "date" } }, "required": [ "from", "through", "timeZone", "days", "previousFrom", "previousThrough" ] }, "LearningTotals": { "type": "object", "properties": { "questions": { "type": "integer" }, "attempts": { "type": "integer" }, "firstTryCorrect": { "type": "integer" }, "firstTryTotal": { "type": "integer" }, "legacyQuestions": { "type": "integer" }, "activeDays": { "type": "integer" }, "accuracy": { "type": [ "number", "null" ] } }, "required": [ "questions", "attempts", "firstTryCorrect", "firstTryTotal", "legacyQuestions", "accuracy" ] }, "LearningDay": { "type": "object", "properties": { "day": { "type": "string", "format": "date" }, "math": { "type": "integer" }, "reading": { "type": "integer" }, "attempts": { "type": "integer" }, "firstTryCorrect": { "type": "integer" }, "firstTryTotal": { "type": "integer" }, "accuracy": { "type": [ "number", "null" ] } }, "required": [ "day", "math", "reading", "attempts", "firstTryCorrect", "firstTryTotal", "accuracy" ] }, "LearningMetrics": { "type": "object", "properties": { "range": { "$ref": "#/components/schemas/LearningRange" }, "current": { "$ref": "#/components/schemas/LearningTotals" }, "previous": { "$ref": "#/components/schemas/LearningTotals" }, "daily": { "type": "array", "items": { "$ref": "#/components/schemas/LearningDay" } }, "change": { "type": [ "number", "null" ] } }, "required": [ "range", "current", "previous", "daily", "change" ] }, "LearningProvider": { "type": "object", "properties": { "configured": { "type": "boolean" }, "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "configured", "provider", "model" ] }, "LearningProgress": { "type": "object", "properties": { "metrics": { "$ref": "#/components/schemas/LearningMetrics" }, "llm": { "$ref": "#/components/schemas/LearningProvider" }, "reportAllowance": { "$ref": "#/components/schemas/LearningReportAllowance" } }, "required": [ "metrics", "llm", "reportAllowance" ] }, "LearningAction": { "type": "object", "properties": { "ref": { "type": "string" }, "kind": { "type": "string", "enum": [ "add_math", "add_reading", "remove_math", "remove_reading" ] }, "subject": { "type": "string", "enum": [ "math", "reading" ] }, "prompt": { "type": "string" }, "answer": { "type": "string" }, "grade": { "type": "string" }, "bankId": { "type": "string" }, "evidenceRef": { "type": "string" }, "standard": { "type": [ "string", "null" ] }, "topic": { "type": [ "string", "null" ] }, "explanation": { "type": [ "string", "null" ] }, "templateVersion": { "type": "integer" } }, "required": [ "ref", "kind", "subject", "prompt", "answer", "grade" ] }, "LearningSuggestion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reportId": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "why": { "type": "string" }, "evidenceRefs": { "type": "array", "items": { "type": "string" } }, "action": { "$ref": "#/components/schemas/LearningAction" }, "status": { "type": "string", "enum": [ "pending", "applied", "rejected", "stale" ] }, "decidedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "reportId", "title", "why", "evidenceRefs", "action", "status", "decidedAt" ] }, "LearningEvidence": { "type": "object", "properties": { "ref": { "type": "string" }, "bankId": { "type": [ "string", "null" ] }, "prompt": { "type": "string" }, "answer": { "type": "string" }, "subject": { "type": "string" }, "grade": { "type": "string" }, "questions": { "type": "integer" }, "days": { "type": "integer" }, "firstTryCorrect": { "type": "integer" }, "firstTryTotal": { "type": "integer" }, "wrongAttempts": { "type": "integer" }, "legacyQuestions": { "type": "integer" }, "accuracy": { "type": [ "number", "null" ] }, "removalEligible": { "type": "boolean" }, "examples": { "type": "array", "items": { "type": "object", "properties": { "answer": { "type": [ "string", "null" ] }, "correct": { "type": [ "boolean", "null" ] }, "legacy": { "type": "boolean" } }, "required": [ "answer", "correct", "legacy" ] } } }, "required": [ "ref", "bankId", "prompt", "answer", "subject", "grade", "questions", "days", "firstTryCorrect", "firstTryTotal", "wrongAttempts", "legacyQuestions", "accuracy", "removalEligible", "examples" ] }, "LearningInsight": { "type": "object", "properties": { "title": { "type": "string" }, "text": { "type": "string" }, "evidenceRefs": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "text", "evidenceRefs" ] }, "LearningNarrative": { "type": "object", "properties": { "summary": { "type": "string" }, "strengths": { "type": "array", "items": { "$ref": "#/components/schemas/LearningInsight" } }, "challenges": { "type": "array", "items": { "$ref": "#/components/schemas/LearningInsight" } }, "nextSteps": { "type": "array", "items": { "type": "string" } } }, "required": [ "summary", "strengths", "challenges", "nextSteps" ] }, "LearningReportSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "range": { "$ref": "#/components/schemas/LearningRange" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "model": { "type": [ "string", "null" ] } }, "required": [ "id", "range", "status", "createdAt", "model" ] }, "LearningReport": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "range": { "$ref": "#/components/schemas/LearningRange" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "createdAt": { "type": "string", "format": "date-time" }, "model": { "type": [ "string", "null" ] }, "childId": { "type": "string" }, "grade": { "type": "string" }, "metrics": { "$ref": "#/components/schemas/LearningMetrics" }, "narrative": { "anyOf": [ { "$ref": "#/components/schemas/LearningNarrative" }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/LearningEvidence" } }, "evidenceOmitted": { "type": "integer" }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/LearningSuggestion" } } }, "required": [ "id", "range", "status", "createdAt", "model", "childId", "grade", "metrics", "narrative", "error", "finishedAt", "evidence", "evidenceOmitted", "suggestions" ] }, "CommunityBlockedVideo": { "type": "object", "properties": { "videoId": { "type": "string" }, "title": { "type": [ "string", "null" ], "description": "Public YouTube title; null if unavailable." }, "channelName": { "type": [ "string", "null" ] }, "parentsBlocking": { "type": "integer", "minimum": 0 }, "percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "Distinct parents blocking this item / all current parent accounts × 100. Includes viewer and non-blockers in denominator." } }, "required": [ "videoId", "title", "channelName", "parentsBlocking", "percentage" ], "additionalProperties": false }, "CommunityBlockedChannel": { "type": "object", "properties": { "channelName": { "type": "string", "description": "Trimmed, lowercase channel name." }, "parentsBlocking": { "type": "integer", "minimum": 0 }, "percentage": { "type": "number", "minimum": 0, "maximum": 100, "description": "Distinct parents blocking this item / all current parent accounts × 100. Includes viewer and non-blockers in denominator." } }, "required": [ "channelName", "parentsBlocking", "percentage" ], "additionalProperties": false }, "CommunityBlocks": { "type": "object", "properties": { "totalParents": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "const": 10 }, "generatedAt": { "type": "string", "format": "date-time" }, "videos": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/CommunityBlockedVideo" } }, "channels": { "type": "array", "maxItems": 10, "items": { "$ref": "#/components/schemas/CommunityBlockedChannel" } } }, "required": [ "totalParents", "limit", "generatedAt", "videos", "channels" ], "additionalProperties": false }, "CommunityBlockSelection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Client request ID. Reuse with identical targets on retries." }, "videoIds": { "type": "array", "maxItems": 10, "items": { "type": "string", "pattern": "^[A-Za-z0-9_-]{11}$" }, "default": [] }, "channelNames": { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "default": [] } }, "required": [ "id" ], "additionalProperties": false, "description": "At least one nonempty target array is required. Up to ten of each type. Channel names are normalized; duplicate entries are deduplicated.", "anyOf": [ { "required": [ "videoIds" ], "properties": { "videoIds": { "minItems": 1 } } }, { "required": [ "channelNames" ], "properties": { "channelNames": { "minItems": 1 } } } ] }, "CommunityBlockReceipt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "addedVideos": { "type": "integer", "minimum": 0 }, "addedChannels": { "type": "integer", "minimum": 0 } }, "required": [ "id", "addedVideos", "addedChannels" ], "additionalProperties": false }, "APIQuotaStatus": { "type": "object", "additionalProperties": false, "required": [ "day", "resetAt", "limit", "hasOverride", "used", "rejected", "remaining", "timeZone", "defaultLimit" ], "properties": { "day": { "type": "string", "format": "date" }, "resetAt": { "type": "string", "format": "date-time" }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "hasOverride": { "type": "boolean" }, "used": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "timeZone": { "type": "string", "const": "UTC" }, "defaultLimit": { "type": "integer", "const": 100 } } }, "APIQuotaExceeded": { "type": "object", "required": [ "code", "message", "limit", "used", "remaining", "resetAt", "timeZone" ], "properties": { "code": { "type": "string", "const": "API_DAILY_LIMIT_REACHED" }, "message": { "type": "string" }, "limit": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "const": 0 }, "resetAt": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string", "const": "UTC" } } }, "PremiumAccess": { "type": "object", "additionalProperties": false, "properties": { "enabled": { "type": "boolean", "description": "Compatibility alias for features.iep; true only for Paid Premium." }, "llm": { "$ref": "#/components/schemas/LearningProvider" }, "tier": { "$ref": "#/components/schemas/AccountTier" }, "label": { "type": "string", "enum": [ "Free", "Paid", "Paid Premium" ] }, "features": { "type": "object", "additionalProperties": false, "required": [ "iep" ], "properties": { "iep": { "type": "boolean", "description": "True only for Paid Premium. Authorizes IEP uploads, generation and adoption; existing ownership and rate limits still apply." } } } }, "required": [ "enabled", "llm", "tier", "label", "features" ] }, "IEPQuestion": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "section": { "type": "string", "enum": [ "math", "geometry", "algebra", "reading" ] }, "prompt": { "type": "string", "maxLength": 1000 }, "answer": { "type": "string", "maxLength": 100 }, "passage": { "type": "string", "maxLength": 2000 }, "choices": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 4 }, "goal": { "type": "string", "maxLength": 500 }, "reason": { "type": "string", "maxLength": 500 }, "explanation": { "type": "string", "maxLength": 500 }, "bankId": { "type": [ "string", "null" ] }, "adoptedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "section", "prompt", "answer", "passage", "choices", "goal", "reason", "explanation", "bankId", "adoptedAt" ] }, "IEPProposal": { "type": "object", "additionalProperties": false, "properties": { "summary": { "type": "string" }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/IEPQuestion" }, "maxItems": 24 } }, "required": [ "summary", "questions" ] }, "IEPPlanSummary": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "grade": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] } }, "required": [ "id", "grade", "createdAt", "status" ] }, "IEPPlan": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "grade": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "ready", "failed" ] }, "childId": { "type": "string" }, "proposal": { "oneOf": [ { "$ref": "#/components/schemas/IEPProposal" }, { "type": "null" } ] }, "model": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "grade", "createdAt", "status", "childId", "proposal", "model", "error", "finishedAt" ] }, "IEPProgram": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "mathCount": { "type": "integer", "minimum": 0 }, "readingCount": { "type": "integer", "minimum": 0 } }, "required": [ "revision", "mathCount", "readingCount" ] }, "IEPCleared": { "type": "object", "additionalProperties": false, "properties": { "mathCount": { "type": "integer", "minimum": 0 }, "readingCount": { "type": "integer", "minimum": 0 } }, "required": [ "mathCount", "readingCount" ] }, "IEPExtractedText": { "type": "object", "additionalProperties": false, "properties": { "text": { "type": "string" }, "pages": { "type": [ "integer", "null" ] } }, "required": [ "text", "pages" ] }, "AccountTier": { "type": "string", "enum": [ "free", "paid", "paid_premium" ], "description": "Family-wide level assigned by the TubeQuest team. Defaults to free. This value does not confirm a payment." }, "AccountPlan": { "type": "object", "additionalProperties": false, "required": [ "tier", "label", "features" ], "properties": { "tier": { "$ref": "#/components/schemas/AccountTier" }, "label": { "type": "string", "enum": [ "Free", "Paid", "Paid Premium" ] }, "features": { "type": "object", "additionalProperties": false, "required": [ "iep" ], "properties": { "iep": { "type": "boolean", "description": "True only for Paid Premium. Authorizes IEP uploads, generation and adoption; existing ownership and rate limits still apply." } } } } }, "LearningReportAllowance": { "type": "object", "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date" }, "now": { "type": "string", "format": "date-time" }, "timeZone": { "type": "string" }, "limit": { "type": "integer", "const": 1 }, "used": { "type": "integer", "minimum": 0, "maximum": 1 }, "remaining": { "type": "integer", "minimum": 0, "maximum": 1 }, "resetAt": { "type": "string", "format": "date-time" }, "reportId": { "type": [ "string", "null" ] } }, "required": [ "date", "now", "timeZone", "limit", "used", "remaining", "resetAt", "reportId" ] } } } }