Reports Integrator API · v1
Pass Platform3 IDs through unchanged. After the declared upstream gates open, AlphaTest will compose live QTI, Results, Content, CASE, OneRoster, Analytics, and mastery-engine facts—so AcmeTest can show a score, the exact gaps, and the evidence without calculating or storing learning facts.
Built for the AcmeTest maintainer
Use the QTI attempt ID you already have, ask for a bounded report view, render the returned state and evidence, and branch on stable problem types. The API never asks your app to join Platform3 products or infer mastery.
503 dependency-unavailable, never an empty or synthetic success. See the release matrix · Read the build-eligibility policy.Cold integration guide
The sandbox lets you prove response parsing and UI wiring against exact contract fixtures. It is intentionally not a substitute for production auth, tenant isolation, writes, or upstream-call evidence.
Use the fixed sandbox attempt att_7F3k9. The Authorization header is accepted only so your request code has the production shape; the synthetic sandbox does not validate or inspect it.
export REPORTS_SANDBOX_URL="https://alphatest-andymontgomery-9773s-projects.vercel.app/reports/integrator_api/customer_website/sandbox"
export REPORTS_TOKEN="${REPORTS_TOKEN:-sandbox-not-validated}"
curl --fail-with-body --get \
"$REPORTS_SANDBOX_URL/v1/attempt-reports/att_7F3k9" \
-H "Authorization: Bearer $REPORTS_TOKEN" \
-H "Accept: application/json" \
--data-urlencode "view=evidence" \
--output report.json
node -e 'const r=require("./report.json"); if(r.score.value!==87||r.mastery[0].caseGuid!=="case_tx_5_3a"||r.mastery[0].evidence[0].qtiItemId!=="item_301") process.exit(1); console.log(`${r.gate.status}: ${r.mastery[0].state} ${r.mastery[0].caseGuid}`)'Expected: fail: gap case_tx_5_3a. The response also carries QTI item/outcome evidence, a Results component id, and source receipts. Compare the normative fixture · Evidence decision
The second fixed attempt proves the adaptive-only branch: a mastery-scale score, uncertainty, calibration and scale versions, stopping reason, administered item count, and evidence-backed mastered/not-yet/gap classifications.
curl --fail-with-body --get \
"$REPORTS_SANDBOX_URL/v1/attempt-reports/att_diag_8K2m" \
-H "Authorization: Bearer $REPORTS_TOKEN" \
-H "Accept: application/json" \
--data-urlencode "view=evidence" \
--output diagnostic.json
node -e 'const r=require("./diagnostic.json"); const gap=r.mastery.find(x=>x.caseGuid==="case_math5_alg_patterns"); if(r.testKind!=="adaptive_diagnostic"||r.gate!==null||r.diagnostic.scaleScore!==214.6||r.diagnostic.scaleVersion!=="ams-math-2"||r.diagnostic.calibrationVersion!=="cal-2026-01"||r.diagnostic.standardError!==2.7||r.diagnostic.stoppingReason!=="classifications_complete"||r.diagnostic.administeredItemCount!==24||gap?.state!=="gap"||!gap.evidence[0].qtiItemId) process.exit(1); console.log(`${r.diagnostic.scaleScore} ± ${r.diagnostic.standardError}: ${gap.state} ${gap.caseGuid}`)'Expected: 214.6 ± 2.7: gap case_math5_alg_patterns. gate is null because it does not apply; nweaNormsSet is null because this fixture claims no MAP crosswalk. Compare the normative fixture · Diagnostic decision
These fixtures make the exact write request, pagination, and two audit projections callable without implying that Results, Caliper, Analytics, or QTI were contacted. Materialize always returns the same fixed synthetic operation and does not inspect the key or body. Candidate history enforces testKind against its fixture rows: an unmatched kind returns an empty terminal page.
curl --fail-with-body \
"$REPORTS_SANDBOX_URL/v1/attempt-reports:materialize" \
-X POST \
-H "Authorization: Bearer $REPORTS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: acmetest-att-7F3k9-v1" \
--data '{"attemptId":"att_7F3k9","administrationId":"admin_fall_2026","view":"summary"}'
curl --fail-with-body --get \
"$REPORTS_SANDBOX_URL/v1/candidates/student_1042/attempt-reports" \
-H "Authorization: Bearer $REPORTS_TOKEN" \
--data-urlencode "testKind=mastery_gate" \
--data-urlencode "limit=2" \
--output attempts-page-1.json
NEXT_CURSOR=$(node -p 'require("./attempts-page-1.json").nextCursor')
curl --fail-with-body --get \
"$REPORTS_SANDBOX_URL/v1/candidates/student_1042/attempt-reports" \
-H "Authorization: Bearer $REPORTS_TOKEN" \
--data-urlencode "testKind=mastery_gate" \
--data-urlencode "limit=2" \
--data-urlencode "cursor=$NEXT_CURSOR" \
--output attempts-page-2.json
node -e 'const p=require("./attempts-page-2.json"); if(p.nextCursor!==null||p.hasMore!==false) process.exit(1); console.log(`pagination complete: ${p.data.length} final row`)'
curl --fail-with-body \
"$REPORTS_SANDBOX_URL/v1/attempt-reports/att_7F3k9/readiness" \
-H "Authorization: Bearer $REPORTS_TOKEN"
curl --fail-with-body \
"$REPORTS_SANDBOX_URL/v1/forms/qti_form_math5_b/equivalence" \
-H "Authorization: Bearer $REPORTS_TOKEN"Expected list result: pagination complete: 1 final row. The readiness response is not_ready because the same attempt's gate failed at 0.71 < 0.80. The sandbox only resolves the request shapes listed on its fixture manifest. It does not implement real writes, replay semantics, arbitrary IDs, auth failures, or dependency failures.
Production handoff
Keep these calls disabled until the release matrix names a production API origin and Gate E's signed manifest proves the build was eligible. Unlike the sandbox, these routes must verify the tenant JWT and compose real Platform3 facts.
Use a signed tenant-scoped Platform JWT. Reads require reports:read; materialization requires reports:write. Tenant routing comes only from tenantId in the verified token.
export REPORTS_BASE_URL="https://YOUR_REPORTS_API_ORIGIN"
export REPORTS_TOKEN="YOUR_SIGNED_PLATFORM_JWT"The origin placeholder is deliberate: no production API origin is published while the routes are unreleased. Required claims and authorization behavior · Decision ITD-021
After Gates B, C, and D open together, this retry-safe orchestration writes settled components to Results, emits Caliper, reads Results back, and composes the report. The approved body requires both the QTI attempt ID and its AlphaTest administration ID; retain the latter from your assignment flow. Keep the same key for an identical retry. Do not call the path before it is released.
curl --fail-with-body \
"$REPORTS_BASE_URL/v1/attempt-reports:materialize" \
-X POST \
-H "Authorization: Bearer $REPORTS_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Idempotency-Key: acmetest-att-7F3k9-v1" \
--data '{"attemptId":"qti-attempt-01J0EXAMPLE","administrationId":"admin_fall_2026","view":"summary"}'After Gates C and D open in one coherent release, view=evidence returns identity, settled score, test-kind detail, standards/KCs, contributing QTI outcomes, source freshness, and explicit omission metadata. Before release, the path has no production contract.
curl --fail-with-body --get \
"$REPORTS_BASE_URL/v1/attempt-reports/qti-attempt-01J0EXAMPLE" \
-H "Authorization: Bearer $REPORTS_TOKEN" \
-H "Accept: application/json" \
--data-urlencode "view=evidence"Views: summary, standards, evidence · Exact response fixture · AttemptReport fields
After Gate C, Gate D, and the authoritative candidate/attempt index open together, candidate lists use stable, tenant-bound cursor pagination. Every row must satisfy every supplied server-enforced filter after authorization, including qtiTestId, testKind, status, and modifiedSince; an unmatched filter returns 200 with an empty terminal page. The alias testId is intentionally unsupported and returns the typed unsupported-parameter problem. Send the returned cursor with the same filters, sort, and limit; never decode it. Before release, the path has no production contract.
curl --fail-with-body --get \
"$REPORTS_BASE_URL/v1/candidates/student_1042/attempt-reports" \
-H "Authorization: Bearer $REPORTS_TOKEN" \
--data-urlencode "testKind=mastery_gate" \
--data-urlencode "modifiedSince=2026-07-01T00:00:00Z" \
--data-urlencode "limit=25"Response fixture · Filters, sort, and cursor validation · Server-enforced filter invariants
It keeps calls disabled until the release matrix names a production origin; after release, it uses gate.status or score.value as returned, renders every mastery[] gap with its caseGuid and nested evidence[], exposes sources[] freshness, follows nextCursor unchanged, and branches on problem type—never on message text.
Post-gate recipes
These normative recipes become populated only after Gates C and D open. The authoritative attempt-to-Results-to-Content composition determines test kind; callers do not select it. One unified runtime returns only the evidence that kind can support.
Render the Results-owned pass/fail under the immutable blueprint criteria. A failure includes every gap; missing criteria or coverage evidence is indeterminate, never pass.
report.gate.statusreport.gate.gapCaseGuids[]report.mastery[].evidence[]Show the RIT-like mastery scale score beside its uncertainty, calibration version, stopping reason, and mastered/not-yet/gap map. Any MAP comparison is a labeled crosswalk—not an NWEA-issued score.
report.diagnostic.scaleScorereport.diagnostic.standardErrorreport.mastery[].stateUse the same endpoint for weekly unit tests and quizzes. Formative reports do not claim grade-level certification or external readiness unless their blueprint carries qualifying coverage evidence.
report.testKind === "formative"report.mastery[]report.sources[]Readiness · Gates C+D
After Gates C and D open together, only complete coverage at equal-or-higher DOK plus satisfied gate criteria can produce projected_pass. Rule gate-implies-readiness version 2 means the attempt's gate must be pass, coverageFraction must equal 1, dokDominance must be satisfied, and qualifying blueprint slots must be nonempty. A failed gate produces not_ready; missing or stale evidence produces indeterminate. Before release, the route is absent.
curl --fail-with-body \
"$REPORTS_BASE_URL/v1/attempt-reports/qti-attempt-01J0EXAMPLE/readiness" \
-H "Authorization: Bearer $REPORTS_TOKEN"The endpoint is reserved in architecture; the approved field contract is the embedded ReadinessReport projection. Readiness decision
Parallel forms · Gates A+D
After Gates A and D open together, inspect coverage/DOK match, sample sizes, method, confidence interval, tolerance, decision, analysis version, and the downloadable audit artifact. Before release, the route is absent. insufficient_evidence remains first-class post-gate.
curl --fail-with-body \
"$REPORTS_BASE_URL/v1/forms/qti_form_math5_b/equivalence" \
-H "Authorization: Bearer $REPORTS_TOKEN"The endpoint is reserved in architecture; the dictionary publishes the minimum post-gate EquivalenceReport obligation, while Analytics still must supply the owning wire contract before release. Equivalence decision
Endpoint reference
Once a route is released, successes use application/json and failures use RFC 9457 application/problem+json.
/v1/attempt-reports/{attemptId}Draft exact contract · Gates C+D
GET/v1/candidates/{candidateSourcedId}/attempt-reportsDraft exact contract · C+D+index
GET/v1/attempt-reports/{attemptId}/readinessReserved · Gates C+D · decision semantics
GET/v1/forms/{qtiTestId}/equivalenceReserved · Gates A+D
GET/v1/classes/{classSourcedId}/cohort-reportReserved · Gates A+D
GET/v1/schools/{schoolSourcedId}/grades/{grade}/cohort-reportReserved · Gates A+D
POST/v1/attempt-reports:materializeDraft exact contract · Gates B+C+D
The bundled data dictionary gives every request and response field a stable anchor, owning system, validation rule, and architecture citation.
Build safely
The server fails closed at every tenant-data boundary.
Required: sub, tenantId, iat, exp, role, and permission scope. Resource claims can narrow student, class, and school access. Production exposes no token-mint endpoint; short-lived reviewer credentials are minted out of band by the deployment pipeline.
A missing resource and one outside the token’s claims return the same safe detail. Do not treat 404 as proof that an upstream entity does not exist.
Authorization decisionAfter Gates B, C, and D open, an identical materialize retry within 24 hours suppresses writes, preserves operationId, recomposes current Platform3 truth, and returns Idempotent-Replayed: true. Today materialization is not deployed.
After release, branch on absolute type, HTTP status, and retryable. Correlate support with requestId and traceId.
{
"type": "https://alphatest-andymontgomery-9773s-projects.vercel.app/reports/integrator_api/data_dictionary/problems/idempotency-conflict",
"title": "Idempotency key conflicts with an earlier request",
"status": 409,
"detail": "Use a new Idempotency-Key for a different request body.",
"instance": "/problems/occurrences/req_Z2d6",
"requestId": "req_Z2d6",
"traceId": "trace_M9p1",
"retryable": false,
"dependency": null,
"fieldErrors": null,
"operationId": "op_93wK"
}Gap declarations
A local substitute that looks correct would violate the product contract. Closed gates keep routes unreleased; after release, transient dependency failures use typed problems.
The class, school-grade, and form-equivalence routes are reserved but not deployed. Platform3 must publish and verify a production Analytics URL and versioned schema first. Reports never computes aggregates or equivalence privately.
Gate A decisionThe client-facing materialize request is specified, but the upstream Results test_result_components write/read schema and retry-safe Caliper protocol are not. Materialize remains undeployed; no guessed mapping, local outbox of learning facts, or component table is allowed.
Platform3 confirms authenticated ?qtiAttemptId= lookup, but its published response still lacks the dereferenceable candidate, administration, QTI session/test/item outcomes, Content test spec, test kind, gate, mastery/KC, and Results components required for a report. Attempt detail, candidate lists, readiness, and materialization therefore remain undeployed—never partial reports or producer-id guesses.
No capability releases until one immutable unified runtime passes the three-kind matrix and two production-signed, disjoint tenant fixtures prove same-tenant success, bidirectional non-enumerating denial, anonymous rejection, and cache/idempotency/trace isolation. An unavailable credential or fixture keeps certification inconclusive and the routes closed.
ITD-031 release proofSpecification work can continue, but implementation, surface QC, and integration cannot start until one signed prerequisite manifest dereferences every applicable immutable A/B/C/D receipt. Adaptive diagnostics additionally require production-learner QTI member/KC evidence, acknowledged Results components, and Caliper read-back. Stubs, sandbox payloads, public token mints, and permanent 503s do not open this gate.
ITD-033 build eligibilityPlatform3 remains the record
Attempts and sessions stay in QTI. Settled outcomes and mastery stay in Results. Cohort rollups stay in Analytics. Blueprints stay in Content, standards in CASE, and rosters in OneRoster. Every response includes source resource IDs, observed times, versions or ETags, and freshness status.