{ "openapi": "3.1.0", "info": { "title": "Alpha Analytics", "description": "The Alpha Analytics API serves derived facts: per-student, per-window, policy-named rollups and delta ledgers computed from Events, Results, NWEA MAP, People & Orgs, and Curriculum policy. Measures include windowed XP, school-day minutes, accuracy, completion, and MAP growth rollups versioned by supersession. Ledgers hold immutable mastery and event-time delta history. Source import is the write path, with import receipts tracked as entities. Uses cursor pagination, flat envelopes, and RFC 7807 errors.", "version": "1.0" }, "tags": [ { "name": "Accuracy Rollup", "description": "Correct and total question accuracy for a student, subject, and window." }, { "name": "Completion Rollup (evidence)", "description": "Completion evidence rollup for debug and audit. Not the preferred consumer contract — progress answers live on Results progress reads." }, { "name": "Event Time Fact", "description": "Per-event active, inactive, and waste seconds derived from Events activity. Audit grain for the minutes numerator." }, { "name": "MAP Growth Rollup (Growth X)", "description": "MAP Growth X rollup. Exposes startRit and conditionalGrowthPercentile publicly; growthPercentile mirrors conditionalGrowthPercentile. Derived grades come from NWEAMap rit-to-grade reference." }, { "name": "Mastery Delta", "description": "Knowledge-component state transition deltas derived from Results mastery. Each row is an immutable effective-at transition fact." }, { "name": "School Day Minutes", "description": "Minutes per enrolled school day (and per subject). Numerator from Events activity; denominator from the People & Orgs school calendar under the school-day policy." }, { "name": "Source Import (receipt)", "description": "Receipt for the source-import adapter door. The import POST is anchored here; status is this entity's plain GET. Domain dedup keeps sourceBatchRef and sourcePayloadHash alongside the platform idempotency table." }, { "name": "Time Window Rollup", "description": "Windowed active, inactive, and waste-seconds rollup for a student and subject. Feeds the minutes metric check." }, { "name": "XP Rollup", "description": "XP window rollup computed as a pure function of the Results XP ledger under the Curriculum XP-goal policy. Fastmath stays its own subject." } ], "paths": { "/analytics/v1/accuracy-rollups": { "get": { "operationId": "listAccuracyRollups", "summary": "List accuracy rollups", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Accuracy Rollup" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "subjectId", "in": "query", "description": "Canonical subjectId only — display aliases are a 400.", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "windowKind", "in": "query", "schema": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ] }, "x-filter": { "column": "windowKind", "operator": "eq" } }, { "name": "nullReason", "in": "query", "schema": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ] }, "x-filter": { "column": "nullReason", "operator": "eq" } }, { "name": "qualityStatus", "in": "query", "schema": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ] }, "x-filter": { "column": "qualityStatus", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccuracyRollup" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/accuracy-rollups/{studentId}/{subjectId}/{windowKind}/{windowStart}/{windowEnd}/{calculationVersion}": { "get": { "operationId": "getAccuracyRollup", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Accuracy Rollup" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowKind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowStart", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "windowEnd", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccuracyRollup" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (accuracy_rollup_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/completion-rollups": { "get": { "operationId": "listCompletionRollups", "summary": "List completion EVIDENCE rollups (not the preferred consumer contract)", "description": "Evidence/debug surface only. Preferred consumer contract is Results progress reads. Do not wire Learning-Report/GOALS to this endpoint.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Completion Rollup (evidence)" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "subjectId", "in": "query", "description": "Canonical subjectId only — display aliases are a 400.", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "nullReason", "in": "query", "schema": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ] }, "x-filter": { "column": "nullReason", "operator": "eq" } }, { "name": "qualityStatus", "in": "query", "schema": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ] }, "x-filter": { "column": "qualityStatus", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "completionScope", "in": "query", "schema": { "type": "string", "enum": [ "course", "subject", "track", "track_level", "grade_level", "segment" ] }, "x-filter": { "column": "completionScope", "operator": "eq" } }, { "name": "scopeId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "scopeId", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompletionRollup" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/completion-rollups/{studentId}/{completionScope}/{scopeId}/{subjectId}/{windowStart}/{windowEnd}/{calculationVersion}": { "get": { "operationId": "getCompletionRollup", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Completion Rollup (evidence)" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "completionScope", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "scopeId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowStart", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "windowEnd", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletionRollup" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (completion_rollup_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/event-time-facts": { "get": { "operationId": "listEventTimeFacts", "summary": "List event time facts (numerator audit grain)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Event Time Fact" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "subjectId", "in": "query", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "factKind", "in": "query", "schema": { "type": "string", "enum": [ "active_seconds", "inactive_seconds", "waste_seconds" ] }, "x-filter": { "column": "factKind", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventTimeFact" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/event-time-facts/{studentId}/{sourceEventId}/{sourceFactKey}/{calculationVersion}": { "get": { "operationId": "getEventTimeFact", "summary": "Get one event time fact by natural key", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Event Time Fact" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sourceEventId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sourceFactKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTimeFact" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (event_time_fact_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/map-growth-rollups": { "get": { "operationId": "listMapGrowthRollups", "summary": "List MAP Growth X rollups", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "MAP Growth Rollup (Growth X)" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "subjectId", "in": "query", "description": "Canonical subjectId only — display aliases are a 400.", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "nullReason", "in": "query", "schema": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ] }, "x-filter": { "column": "nullReason", "operator": "eq" } }, { "name": "qualityStatus", "in": "query", "schema": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ] }, "x-filter": { "column": "qualityStatus", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "canonicalTermId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "canonicalTermId", "operator": "eq" } }, { "name": "growthWindow", "in": "query", "schema": { "type": "string", "enum": [ "fall_to_fall", "fall_to_winter", "winter_to_winter", "winter_to_spring", "spring_to_spring", "fall_to_spring", "baseline_to_current", "term", "custom" ] }, "x-filter": { "column": "growthWindow", "operator": "eq" } }, { "name": "normsSet", "in": "query", "schema": { "type": "string", "enum": [ "2020", "2025" ] }, "x-filter": { "column": "normsSet", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MapGrowthRollup" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/map-growth-rollups/{studentId}/{subjectId}/{canonicalTermId}/{growthWindow}/{normsSet}/{calculationVersion}": { "get": { "operationId": "getMapGrowthRollup", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "MAP Growth Rollup (Growth X)" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "canonicalTermId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "growthWindow", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "normsSet", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MapGrowthRollup" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (map_growth_rollup_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/mastery-deltas": { "get": { "operationId": "listMasteryDeltas", "summary": "List mastery deltas", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Mastery Delta" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "kcId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "kcId", "operator": "eq" } }, { "name": "stateDimension", "in": "query", "schema": { "type": "string", "enum": [ "initial_mastery", "current_retention", "durable_mastery", "fluency_state", "next_due_at" ] }, "x-filter": { "column": "stateDimension", "operator": "eq" } }, { "name": "subjectId", "in": "query", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MasteryDelta" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/mastery-deltas/{studentId}/{kcId}/{stateDimension}/{effectiveAt}/{calculationVersion}": { "get": { "operationId": "getMasteryDelta", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Mastery Delta" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "kcId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "stateDimension", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "effectiveAt", "in": "path", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MasteryDelta" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (mastery_delta_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/school-day-minutes": { "get": { "operationId": "listSchoolDayMinutes", "summary": "List school-day minutes measures", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "School Day Minutes" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "subjectId", "in": "query", "description": "Canonical subjectId only — display aliases are a 400.", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "windowKind", "in": "query", "schema": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ] }, "x-filter": { "column": "windowKind", "operator": "eq" } }, { "name": "nullReason", "in": "query", "description": "Reportability: default consumers pass nullReason=none.", "schema": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ] }, "x-filter": { "column": "nullReason", "operator": "eq" } }, { "name": "qualityStatus", "in": "query", "schema": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ] }, "x-filter": { "column": "qualityStatus", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "schoolId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "schoolId", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SchoolDayMinutes" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/school-day-minutes/{studentId}/{schoolId}/{subjectId}/{windowKind}/{windowStart}/{windowEnd}/{calculationVersion}": { "get": { "operationId": "getSchoolDayMinutes", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "School Day Minutes" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "schoolId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowKind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowStart", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "windowEnd", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchoolDayMinutes" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (school_day_minutes_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/source-imports": { "get": { "operationId": "listSourceImports", "summary": "List source-import receipts", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "importKind", "in": "query", "schema": { "type": "string", "enum": [ "timeback-xp-time-accuracy", "timeback-map", "timeback-grade-mastery", "timeback-completion", "event_close_replay", "result_close_replay", "migration_reconcile" ] }, "x-filter": { "column": "importKind", "operator": "eq" } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "received", "running", "materialized", "partially_rejected", "rejected", "failed" ] }, "x-filter": { "column": "status", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SourceImport" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/source-imports/{importId}": { "get": { "operationId": "getSourceImport", "summary": "Get one source-import receipt (the command status endpoint)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceImport" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (source_import_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/source-imports/{adapter}": { "post": { "operationId": "importSourceRows", "summary": "THE source-import adapter door (landing zone)", "description": "Canonicalize at write time; compute measures from RAW grain never ingest pre-computed rollups; reconcile to the envelope; write receipt + materialized measures with policyRef + real source*Refs; supersede prior current rows. ONE transaction. Invalid adapter → 400 with allowedValues.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "adapter", "in": "path", "required": true, "description": "Registered adapter name (invalid → 400 with allowedValues).", "schema": { "type": "string", "enum": [ "timeback-xp-time-accuracy", "timeback-map", "timeback-grade-mastery", "timeback-completion", "event_close_replay", "result_close_replay", "migration_reconcile" ] } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "The idempotency key (max 128 chars). REQUIRED — absent returns 428. A completed replay returns the stored response at 200 with idempotency-replayed: true.", "schema": { "type": "string", "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sourceBatchRef": { "type": "string", "minLength": 1, "maxLength": 256 }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "minItems": 1, "description": "Adapter-shaped open objects; required fields vary by adapter." } }, "required": [ "sourceBatchRef", "rows" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceImport" } } }, "headers": { "idempotency-replayed": { "description": "true when this response is a stored idempotent replay (the hook did not run).", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceImport" } } }, "headers": { "idempotency-replayed": { "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict — an operation with this Idempotency-Key is already in progress (60s lock).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Problem (analytics:row_validation_failed).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this operation requires the Idempotency-Key header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/students/{studentId}/grade-level-status": { "get": { "operationId": "getGradeStatus", "summary": "The two named age-grade comparisons", "description": "Computed from peopleAndOrgs age_grade_history as-of + results working_grade/HMG as-of. Never a hidden third age-grade rule. Unqualified ahead/behind aliases are deprecated companions.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "query", "required": true, "description": "Canonical subject — display aliases rejected.", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] } }, { "name": "asOf", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "studentId": { "type": "string" }, "subjectId": { "type": "string" }, "asOfDate": { "type": [ "string", "null" ], "format": "date" }, "ageGrade": { "type": [ "integer", "null" ] }, "workingGrade": { "type": [ "number", "null" ] }, "highestMasteredGrade": { "type": [ "integer", "null" ] }, "workingAgeGradeStatus": { "type": [ "number", "null" ] }, "masteredAgeGradeStatus": { "type": [ "number", "null" ] }, "workingStatusLabel": { "type": "string", "enum": [ "working_behind_age_grade", "working_at_age_grade", "working_above_age_grade" ] }, "masteredStatusLabel": { "type": "string", "enum": [ "mastered_behind_age_grade", "mastered_at_age_grade", "mastered_above_age_grade" ] }, "basis": { "type": "object" }, "sourceRefs": { "type": "object" } }, "required": [ "studentId", "subjectId", "ageGrade", "workingGrade", "highestMasteredGrade", "workingAgeGradeStatus", "masteredAgeGradeStatus", "workingStatusLabel", "masteredStatusLabel", "basis", "sourceRefs" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/students/{studentId}/within-grade-pacing": { "get": { "operationId": "getWithinGradePacing", "summary": "Within-grade pacing evidence (companion to Results progress reads)", "description": "Compares Results grade-level progress to elapsed-school-year percent from the P&O calendar. Student-facing pacing answer remains a Results read; this is qualified Analytics evidence.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] } }, { "name": "asOf", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "studentId": { "type": "string" }, "subjectId": { "type": "string" }, "asOfDate": { "type": [ "string", "null" ], "format": "date" }, "gradeLevelProgress": { "type": [ "number", "null" ] }, "elapsedSchoolYearPercent": { "type": [ "number", "null" ] }, "pacingDelta": { "type": [ "number", "null" ] }, "nullReason": { "type": [ "string", "null" ] }, "sourceRefs": { "type": "object" } }, "required": [ "studentId", "subjectId" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/rit-to-grade": { "get": { "operationId": "mirrorRitToGrade", "summary": "RIT-to-grade MIRROR read (sources from nweamap)", "description": "Delegates to nweamap:lookupRitToGrade and stamps PowerPath/NWEAMap sourceRef metadata. No local RIT table.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "subjectId", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] } }, { "name": "rit", "in": "query", "required": true, "schema": { "type": "number" } }, { "name": "normsSet", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "2020", "2025" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subjectId": { "type": "string" }, "rit": { "type": "number" }, "r50Grade": { "type": [ "number", "null" ] }, "r90Grade": { "type": [ "number", "null" ] }, "effectiveGrade": { "type": [ "number", "null" ] }, "normsSet": { "type": [ "string", "null" ] }, "sourceRef": { "type": "string" } }, "required": [ "subjectId", "rit", "sourceRef" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/rit-to-grade/table": { "get": { "operationId": "mirrorRitToGradeTable", "summary": "RIT-to-grade table MIRROR", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "subjectId", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] } }, { "name": "normsSet", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "2020", "2025" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object" } }, "sourceRef": { "type": "string" } }, "required": [ "rows", "sourceRef" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/norms": { "get": { "operationId": "mirrorNorms", "summary": "Norms MIRROR read (sources from nweamap:mapNormTable)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "subjectId", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] } }, { "name": "normsSet", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "2020", "2025" ] } }, { "name": "rit", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "percentile", "in": "query", "required": false, "schema": { "type": "number" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rit": { "type": [ "number", "null" ] }, "percentile": { "type": [ "number", "null" ] }, "normsSet": { "type": [ "string", "null" ] }, "sourceRef": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object" } } }, "required": [ "sourceRef" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/norms/table": { "get": { "operationId": "mirrorNormsTable", "summary": "Norms table MIRROR", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "subjectId", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] } }, { "name": "normsSet", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "2020", "2025" ] } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object" } }, "sourceRef": { "type": "string" } }, "required": [ "rows", "sourceRef" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/r90": { "get": { "operationId": "mirrorR90", "summary": "Deprecated /r90 alias — delegates to mirrorRitToGrade", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "subjectId", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ] } }, { "name": "rit", "in": "query", "required": true, "schema": { "type": "number" } } ], "deprecated": true, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "r50Grade": { "type": [ "number", "null" ] }, "r90Grade": { "type": [ "number", "null" ] }, "effectiveGrade": { "type": [ "number", "null" ] }, "sourceRef": { "type": "string" } }, "required": [ "sourceRef" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/r90/table": { "get": { "operationId": "mirrorR90Table", "summary": "Deprecated /r90/table alias — delegates to mirrorRitToGradeTable", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "deprecated": true, "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object" } }, "sourceRef": { "type": "string" } }, "required": [ "rows", "sourceRef" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/exports": { "post": { "operationId": "exportAnalytics", "summary": "Bulk export of analytics entities", "description": "Receipt-is-an-entity export job. Returns a downloadRef JSON thin slice; clients fetch bytes out-of-band.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Source Import (receipt)" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "The idempotency key (max 128 chars). Optional — when present, the call is replay-protected; a completed replay returns the stored response at 200 with idempotency-replayed: true.", "schema": { "type": "string", "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entities": { "type": "array", "items": { "type": "string" } }, "modifiedSince": { "type": "string", "format": "date-time" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "OK (idempotent replay — the stored first response; idempotency-replayed: true).", "content": { "application/json": { "schema": { "type": "object", "properties": { "exportId": { "type": "string" }, "status": { "type": "string" }, "downloadRef": { "type": "string" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "exportId", "status", "downloadRef" ] } } }, "headers": { "idempotency-replayed": { "description": "true when this response is a stored idempotent replay (the hook did not run).", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "exportId": { "type": "string" }, "status": { "type": "string" }, "downloadRef": { "type": "string" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "exportId", "status", "downloadRef" ] } } }, "headers": { "idempotency-replayed": { "description": "true when this response is a stored idempotent replay (the hook did not run).", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict — an operation with this Idempotency-Key is already in progress (60s lock).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity — this Idempotency-Key was already used with a different request body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this operation requires the Idempotency-Key header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/time-windows": { "get": { "operationId": "listTimeWindows", "summary": "List time-window rollups", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Time Window Rollup" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "subjectId", "in": "query", "description": "Canonical subjectId only — display aliases are a 400.", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "windowKind", "in": "query", "schema": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ] }, "x-filter": { "column": "windowKind", "operator": "eq" } }, { "name": "nullReason", "in": "query", "description": "Reportability: default consumers pass nullReason=none.", "schema": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ] }, "x-filter": { "column": "nullReason", "operator": "eq" } }, { "name": "qualityStatus", "in": "query", "schema": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ] }, "x-filter": { "column": "qualityStatus", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimeWindow" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/time-windows/{studentId}/{subjectId}/{windowKind}/{windowStart}/{windowEnd}/{calculationVersion}": { "get": { "operationId": "getTimeWindow", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Time Window Rollup" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowKind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowStart", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "windowEnd", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeWindow" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (time_window_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/xp-rollups": { "get": { "operationId": "listXpRollups", "summary": "List XP rollups", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "XP Rollup" ], "parameters": [ { "name": "studentId", "in": "query", "schema": { "type": "string" }, "x-filter": { "column": "studentId", "operator": "eq" } }, { "name": "subjectId", "in": "query", "description": "Canonical subjectId only — display aliases are a 400.", "schema": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ] }, "x-filter": { "column": "subjectId", "operator": "eq" } }, { "name": "windowKind", "in": "query", "schema": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ] }, "x-filter": { "column": "windowKind", "operator": "eq" } }, { "name": "nullReason", "in": "query", "schema": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ] }, "x-filter": { "column": "nullReason", "operator": "eq" } }, { "name": "qualityStatus", "in": "query", "schema": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ] }, "x-filter": { "column": "qualityStatus", "operator": "eq" } }, { "name": "modifiedSince", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "x-filter": { "column": "updatedAt", "operator": "gte" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/XpRollup" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/analytics/v1/xp-rollups/{studentId}/{subjectId}/{windowKind}/{windowStart}/{windowEnd}/{calculationVersion}": { "get": { "operationId": "getXpRollup", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "XP Rollup" ], "parameters": [ { "name": "studentId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "subjectId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowKind", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "windowStart", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "windowEnd", "in": "path", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "calculationVersion", "in": "path", "required": true, "schema": { "type": "integer" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/XpRollup" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (xp_rollup_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "AccuracyRollup": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ], "description": "Canonical subject id set at import time; public reads reject display aliases." }, "windowKind": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ], "description": "Window family for this measure (day, fall_term, spring_term, school_year, custom_range)." }, "windowStart": { "type": "string", "format": "date", "description": "Inclusive window start date." }, "windowEnd": { "type": "string", "format": "date", "description": "Exclusive or inclusive window end date (grain bound)." }, "correctQuestionCount": { "type": "integer", "minimum": 0, "description": "Count of correct questions in the window." }, "totalQuestionCount": { "type": "integer", "minimum": 0, "description": "Count of total questions in the window." }, "incorrectQuestionCount": { "type": "integer", "minimum": 0, "description": "Count of incorrect questions in the window." }, "accuracyPercent": { "type": [ "number", "null" ], "description": "correct / total * 100 when total > 0." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current; set on supersession." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete timestamp when the backing source row disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "nullReason": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ], "description": "Why a measure value is null — never a fabricated 0." }, "sourceFactRefs": { "type": "array", "items": { "type": "object" }, "description": "jsonb refs that must dereference to real backing facts (anti-leak)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "subjectId", "windowKind", "windowStart", "windowEnd", "calculationVersion", "correctQuestionCount", "totalQuestionCount", "incorrectQuestionCount", "policyRef", "qualityStatus", "nullReason", "computedAt", "updatedAt" ] }, "CompletionRollup": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "completionScope": { "type": "string", "enum": [ "course", "subject", "track", "track_level", "grade_level", "segment" ], "description": "Scope kind for the completion evidence rollup." }, "scopeId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Identifier of the completion scope instance." }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ], "description": "Canonical subject id set at import time; public reads reject display aliases." }, "windowStart": { "type": "string", "format": "date", "description": "Inclusive window start date." }, "windowEnd": { "type": "string", "format": "date", "description": "Exclusive or inclusive window end date (grain bound)." }, "gradeLevel": { "type": [ "integer", "null" ], "minimum": -1, "maximum": 12, "description": "Typed integer grade position (PreK=-1, K=0, 1..12)." }, "isMainCourse": { "type": [ "boolean", "null" ], "description": "Whether the scope is a main course." }, "progressSourceKind": { "type": [ "string", "null" ], "maxLength": 128, "description": "Which progress evidence grain fed this rollup." }, "xpEarned": { "type": [ "number", "null" ], "description": "XP earned in the completion window." }, "xpRemaining": { "type": [ "number", "null" ], "description": "xpGoal minus netXp when goal is known." }, "completedCount": { "type": "integer", "minimum": 0, "description": "Completed items in the scope." }, "expectedCount": { "type": "integer", "minimum": 0, "description": "Expected items in the scope." }, "completionPercent": { "type": [ "number", "null" ], "description": "completedCount / expectedCount * 100 when expected > 0." }, "numeratorPolicyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy provenance for the numerator." }, "denominatorPolicyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Policy provenance for the denominator." }, "curriculumScopeRefs": { "type": "array", "items": { "type": "object" }, "description": "Curriculum scope pointers for audit." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current; set on supersession." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete timestamp when the backing source row disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "nullReason": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ], "description": "Why a measure value is null — never a fabricated 0." }, "sourceResultRefs": { "type": "array", "items": { "type": "object" }, "description": "jsonb refs into Results result facts (anti-leak)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "completionScope", "scopeId", "subjectId", "windowStart", "windowEnd", "calculationVersion", "completedCount", "expectedCount", "numeratorPolicyRef", "denominatorPolicyRef", "policyRef", "qualityStatus", "nullReason", "computedAt", "updatedAt" ] }, "EventTimeFact": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "sourceEventId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Upstream Events / Caliper event id." }, "sourceFactKey": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable fact key within the source event (active/inactive/waste leg)." }, "sourceClosedAt": { "type": "string", "format": "date-time", "description": "When the source event was closed." }, "factKind": { "type": "string", "enum": [ "active_seconds", "inactive_seconds", "waste_seconds" ], "description": "active_seconds, inactive_seconds, or waste_seconds." }, "secondsDelta": { "type": "number", "description": "Seconds contributed by this fact." }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ], "description": "xpSubject when known (optional). Unscoped rows omit the field." }, "applicationRef": { "type": [ "string", "null" ], "maxLength": 256, "description": "Optional application reference for the activity." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable under composite-natural (G-SUPERSEDE)." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current row for the grain; set when a recompute supersedes this row." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete when backing source disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "sourceEventId", "sourceFactKey", "sourceClosedAt", "factKind", "secondsDelta", "policyRef", "qualityStatus", "calculationVersion", "computedAt", "updatedAt" ] }, "MapGrowthRollup": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ], "description": "mapSubject 6-value enum." }, "canonicalTermId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Canonical term id from NWEAMap — never regexed at read." }, "canonicalTerm": { "type": "object", "properties": { "season": { "type": "string", "enum": [ "fall", "winter", "spring", "summer" ] }, "schoolYear": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{4}$" } }, "required": [ "season", "schoolYear" ], "description": "Structured term metadata.", "additionalProperties": false }, "growthWindow": { "type": "string", "enum": [ "fall_to_fall", "fall_to_winter", "winter_to_winter", "winter_to_spring", "spring_to_spring", "fall_to_spring", "baseline_to_current", "term", "custom" ], "description": "Canonical NWEA growth window." }, "normsSet": { "type": "string", "enum": [ "2020", "2025" ], "description": "NWEA norms edition — never mixed within a rollup." }, "mapScoreId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Stable id of the MAP score grain this rollup covers." }, "mapGrowthWindowRef": { "type": [ "string", "null" ], "maxLength": 512, "description": "Reference to the growth-window source grain." }, "ritScore": { "type": "number", "description": "Observed RIT score for the sitting/window." }, "startRit": { "type": [ "number", "null" ], "description": "Public Growth X contract field." }, "achievementPercentile": { "type": [ "number", "null" ], "description": "Achievement percentile when available." }, "r50Grade": { "type": [ "number", "null" ], "description": "From nweamap:ritToGradeReference." }, "r90Grade": { "type": [ "number", "null" ], "description": "From nweamap:ritToGradeReference." }, "effectiveGrade": { "type": [ "number", "null" ], "description": "Effective instructional grade from the shared calculator." }, "r90GradeLevel": { "type": [ "integer", "null" ], "description": "Integer R90 grade level." }, "r90PercentComplete": { "type": [ "number", "null" ], "description": "Percent complete within the R90 grade band." }, "r90TableVersion": { "type": [ "string", "null" ], "maxLength": 128, "description": "Version stamp of the rit-to-grade reference used." }, "observedGrowth": { "type": [ "number", "null" ], "description": "Observed RIT growth over the growth window." }, "typicalGrowth": { "type": [ "number", "null" ], "description": "Typical growth from norms." }, "projectedGrowth": { "type": [ "number", "null" ], "description": "Projected growth from norms." }, "growthX": { "type": [ "number", "null" ], "description": "observedGrowth ÷ projectedGrowth." }, "conditionalGrowthPercentile": { "type": [ "number", "null" ], "description": "Public Growth X contract field." }, "growthPercentile": { "type": [ "number", "null" ], "description": "Compatibility alias — MUST mirror conditionalGrowthPercentile." }, "growthXTarget": { "type": "number", "description": "2X commitment target under alpha.policy growth_x_target." }, "onTrack": { "type": [ "boolean", "null" ], "description": "Whether the measure meets its policy target." }, "sittingCount": { "type": "integer", "minimum": 0, "description": "Number of MAP sittings contributing to the rollup." }, "retakeCount": { "type": "integer", "minimum": 0, "description": "Number of retakes observed." }, "mapSittingRefs": { "type": "array", "items": { "type": "object" }, "description": "Pointers at nweamap MAP sitting facts." }, "timebackEra": { "type": [ "boolean", "null" ], "description": "≥2025-26 = TimeBack." }, "ninetyNineLevels": { "type": [ "object", "null" ], "description": "99Levels surface derivation." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current; set on supersession." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete timestamp when the backing source row disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "nullReason": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ], "description": "Why a measure value is null — never a fabricated 0." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "subjectId", "canonicalTermId", "growthWindow", "normsSet", "calculationVersion", "mapScoreId", "ritScore", "growthXTarget", "policyRef", "qualityStatus", "nullReason", "computedAt", "sittingCount", "retakeCount", "updatedAt" ] }, "MasteryDelta": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "kcId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Knowledge-component id (loose curriculum ref; Results mastery grain)." }, "stateDimension": { "type": "string", "enum": [ "initial_mastery", "current_retention", "durable_mastery", "fluency_state", "next_due_at" ], "description": "Which mastery state dimension transitioned." }, "effectiveAt": { "type": "string", "format": "date-time", "description": "Immutable transition instant." }, "sourceStateRef": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Pointer to the Results studentKcState / mastery source row." }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing" ], "description": "Canonical mapSubject when known." }, "gradeLevel": { "type": "integer", "minimum": -1, "maximum": 12, "description": "Typed integer grade position (PreK=-1..12)." }, "previousValue": { "type": "object", "description": "Prior KC-state value before the transition." }, "newValue": { "type": "object", "description": "New KC-state value after the transition." }, "deltaValue": { "type": [ "number", "null" ], "description": "Numeric delta when applicable." }, "transitionKind": { "type": "string", "enum": [ "acquired", "improved", "decayed", "review_due", "fluency_changed", "corrected", "blocked" ], "description": "Typed transition kind for the delta." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current; set on supersession." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete timestamp when the backing source row disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "sourceResultRefs": { "type": "array", "items": { "type": "object" }, "description": "jsonb refs into Results result facts (anti-leak)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "kcId", "stateDimension", "effectiveAt", "calculationVersion", "sourceStateRef", "transitionKind", "newValue", "policyRef", "qualityStatus", "computedAt", "updatedAt" ] }, "SchoolDayMinutes": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "schoolId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster org (school) the enrollment window is under.", "x-references": "oneroster:org.sourcedId", "x-onDelete": "restrict" }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ], "description": "Canonical subject id set at import time; public reads reject display aliases." }, "windowKind": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ], "description": "Window family for this measure (day, fall_term, spring_term, school_year, custom_range)." }, "windowStart": { "type": "string", "format": "date", "description": "Inclusive window start date." }, "windowEnd": { "type": "string", "format": "date", "description": "Exclusive or inclusive window end date (grain bound)." }, "schoolDayPolicyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "alpha.policy.school_day provenance stamp." }, "enrolledSchoolDayCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Count of enrolled school days in the window (calendar denominator)." }, "excludedSchoolDayCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "School days excluded (e.g. MAP testing) from the denominator." }, "activeMinutes": { "type": "number", "description": "Active minutes numerator for the school-day minutes measure." }, "minutesPerEnrolledSchoolDay": { "type": [ "number", "null" ], "description": "activeMinutes / enrolledSchoolDayCount when denominator > 0." }, "calendarRefCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of calendar day refs consumed." }, "enrollmentRefCount": { "type": "integer", "minimum": 0, "description": "Number of enrollment refs consumed." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable under composite-natural (G-SUPERSEDE)." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current row for the grain; set when a recompute supersedes this row." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete when backing source disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "nullReason": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ], "description": "Why a measure is null — never a fabricated 0." }, "sourceFactRefs": { "type": "array", "items": { "type": "object" }, "description": "jsonb refs that MUST dereference to real backing facts." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "schoolId", "subjectId", "windowKind", "windowStart", "windowEnd", "calculationVersion", "schoolDayPolicyRef", "activeMinutes", "nullReason", "qualityStatus", "policyRef", "computedAt", "updatedAt" ] }, "SourceImport": { "type": "object", "properties": { "importId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Natural id of this import receipt." }, "importKind": { "type": "string", "enum": [ "timeback-xp-time-accuracy", "timeback-map", "timeback-grade-mastery", "timeback-completion", "event_close_replay", "result_close_replay", "migration_reconcile" ], "description": "Registered adapter / import kind (SOURCE_IMPORT_ADAPTERS)." }, "adapterName": { "type": [ "string", "null" ], "maxLength": 128, "description": "Adapter name as invoked on the path (usually equals importKind)." }, "sourceSystem": { "type": [ "string", "null" ], "maxLength": 128, "description": "Upstream source system label." }, "sourceTable": { "type": [ "string", "null" ], "maxLength": 128, "description": "Upstream source table / stream label." }, "status": { "type": "string", "enum": [ "received", "running", "materialized", "partially_rejected", "rejected", "failed" ], "description": "Receipt processing status." }, "sourceBatchRef": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 256, "description": "Source batch identity for domain dedup (runtime lookup)." }, "sourcePayloadHash": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Canonical hash of the RAW request body (domain dedup + audit)." }, "sourceRowKeyHashes": { "type": "array", "items": { "type": "string" }, "description": "Per-row key hashes for rematerialize / audit." }, "submittedRowCount": { "type": "integer", "minimum": 0, "description": "Rows submitted in the import batch." }, "acceptedRowCount": { "type": "integer", "minimum": 0, "description": "Rows accepted for materialization." }, "materializedRowCount": { "type": "integer", "minimum": 0, "description": "Rows successfully materialized." }, "rejectedRowCount": { "type": "integer", "minimum": 0, "description": "Rows rejected or quarantined." }, "problemCounts": { "type": "object", "description": "Per-problem-code counts (jsonb)." }, "receivedAt": { "type": "string", "format": "date-time", "description": "When the import was received." }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Data-freshness signal for consumers." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "importId", "importKind", "status", "sourcePayloadHash", "submittedRowCount", "acceptedRowCount", "materializedRowCount", "rejectedRowCount", "receivedAt", "createdAt", "updatedAt" ] }, "TimeWindow": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ], "description": "xpSubject (effort-time); fastmath stays itself." }, "windowKind": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ], "description": "Window family for this measure (day, fall_term, spring_term, school_year, custom_range)." }, "windowStart": { "type": "string", "format": "date", "description": "Inclusive window start date." }, "windowEnd": { "type": "string", "format": "date", "description": "Exclusive or inclusive window end date (grain bound)." }, "activeSecondsTotal": { "type": "number", "description": "Sum of active seconds in the window." }, "inactiveSecondsTotal": { "type": "number", "description": "Sum of inactive seconds in the window." }, "wasteSecondsTotal": { "type": "number", "description": "Sum of waste seconds in the window." }, "displayActiveMinutes": { "type": "number", "description": "Active seconds converted to display minutes." }, "sourceFactCount": { "type": "integer", "minimum": 0, "description": "Number of source event-time facts folded into this window." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable under composite-natural (G-SUPERSEDE)." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current row for the grain; set when a recompute supersedes this row." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete when backing source disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "nullReason": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ], "description": "Why a measure is null — never a fabricated 0." }, "sourceFactRefs": { "type": "array", "items": { "type": "object" }, "description": "jsonb refs that MUST dereference to real backing facts." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "subjectId", "windowKind", "windowStart", "windowEnd", "calculationVersion", "activeSecondsTotal", "inactiveSecondsTotal", "wasteSecondsTotal", "displayActiveMinutes", "sourceFactCount", "policyRef", "qualityStatus", "nullReason", "computedAt", "updatedAt" ] }, "XpRollup": { "type": "object", "properties": { "studentId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "OneRoster student identity (tenant-carrying composite FK).", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "subjectId": { "type": "string", "enum": [ "math", "reading", "language", "science", "vocabulary", "writing", "fastmath" ], "description": "xpSubject 7-value enum — fastmath is first-class." }, "windowKind": { "type": "string", "enum": [ "day", "fall_term", "spring_term", "school_year", "custom_range" ], "description": "Window family for this measure (day, fall_term, spring_term, school_year, custom_range)." }, "windowStart": { "type": "string", "format": "date", "description": "Inclusive window start date." }, "windowEnd": { "type": "string", "format": "date", "description": "Exclusive or inclusive window end date (grain bound)." }, "positiveXp": { "type": "number", "description": "Sum of positive XP awards in the window." }, "negativeXp": { "type": "number", "description": "Sum of negative XP (reversals) in the window." }, "xpTotal": { "type": [ "number", "null" ], "description": "Optional total XP (compatibility)." }, "netXp": { "type": "number", "description": "Net XP = positive minus negative." }, "dailyXpGoal": { "type": [ "number", "null" ], "description": "From alpha.policy.analytics.xp_goal grid." }, "enrolledSchoolDayCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Count of enrolled school days in the window (calendar denominator)." }, "xpGoal": { "type": [ "number", "null" ], "description": "dailyXpGoal × enrolledSchoolDayCount." }, "xpRemaining": { "type": [ "number", "null" ], "description": "xpGoal minus netXp when goal is known." }, "onTrack": { "type": [ "boolean", "null" ], "description": "netXp ≥ xpGoal." }, "xpGoalPercent": { "type": [ "number", "null" ], "description": "netXp / xpGoal * 100." }, "xpCompletionPercent": { "type": [ "number", "null" ], "description": "Compatibility completion percent." }, "awardCount": { "type": "integer", "minimum": 0, "description": "Number of positive XP awards contributing to the rollup." }, "reversalCount": { "type": "integer", "minimum": 0, "description": "Number of reversal awards contributing to the rollup." }, "policyRef": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Named alpha.policy.* this measure was computed under." }, "qualityStatus": { "type": "string", "enum": [ "ok", "corrected", "reversed", "source_missing", "source_unlinked", "policy_pending", "adapter_rejected" ], "description": "Measure health; drives reportability." }, "calculationVersion": { "type": "integer", "minimum": 1, "description": "Monotonic version for this grain; part of PK so superseded history rows remain addressable." }, "computedAt": { "type": "string", "format": "date-time", "description": "When this measure row was materialized." }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Null = current; set on supersession." }, "sourceDeletedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Soft-delete timestamp when the backing source row disappeared; never hard-delete." }, "sourceImportId": { "type": "string", "maxLength": 128, "description": "FK to the sourceImport receipt that materialized this row.", "x-references": "sourceImport.importId", "x-onDelete": "restrict" }, "nullReason": { "type": "string", "enum": [ "none", "no_questions", "no_school_days", "no_enrollment", "no_subject_assignment", "source_missing", "source_unlinked", "policy_pending", "not_applicable" ], "description": "Why a measure value is null — never a fabricated 0." }, "sourceLedgerRefs": { "type": "array", "items": { "type": "object" }, "description": "jsonb refs into Results ledger entries (anti-leak)." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentId", "subjectId", "windowKind", "windowStart", "windowEnd", "calculationVersion", "positiveXp", "negativeXp", "netXp", "awardCount", "reversalCount", "policyRef", "qualityStatus", "nullReason", "computedAt", "updatedAt" ] }, "Problem": { "type": "object", "description": "RFC 7807 problem details.", "properties": { "type": { "type": "string", "format": "uri", "description": "A URI identifying the problem type." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "format": "uri", "description": "A URI identifying this occurrence." } }, "required": [ "title", "status" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "servers": [ { "url": "https://alpha.platform4.alphaschool.dev" } ] }