Content Alpha API contract

Current test_spec create and list contract

List: GET /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items?content_kind=test_spec.

Write: POST /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items with Bearer authorization, Content-Type: application/json, and Idempotency-Key. Set content_kind to test_spec; Content derives assessment_role=spec.

Seven required blueprint fields: kc_coverage, item_type_mix, difficulty_constraints, passing_rule, min_forms, max_item_overlap, enemy_item_rule.

Read: GET /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items/{contentId}/blueprint. The POST response's native content_id is the GET response's spec_id. AlphaTest stores no shadow blueprint row.

{
  "content_kind": "test_spec",
  "title": "Grade 7 equations mastery blueprint",
  "language": "en-US",
  "subject_id": "math",
  "target_grade_id": "7",
  "expected_xp": 0,
  "kc_coverage": {
    "case:math:7.ee.b.4": {
      "dok1": 2,
      "dok2": 4
    }
  },
  "item_type_mix": {
    "multiple_choice": 4,
    "numeric_entry": 2
  },
  "difficulty_constraints": {
    "target_mastery_probability": 0.9
  },
  "passing_rule": {
    "policy_ref": "alpha.policy.mastery_cutoff",
    "false_pass_cost": "higher"
  },
  "min_forms": 5,
  "max_item_overlap": 0.2,
  "enemy_item_rule": {
    "no_two_items_on_same_kc_in_one_form": true
  },
  "status": "draft"
}

The Content identity, assessment_role=spec compatibility row, complete seven-field sidecar, initial version, and completed idempotency response commit in one transaction. An identical completed replay returns the same content_id; a changed-body replay returns 409 content.idempotency_conflict.

Assessment publication and trust contract

Integrator authority: An app integrator may invoke the governed paths directly with a Platform-issued tenant-scoped credential. Ordinary publication does not require a per-course owner ruling or a #1769-class trust grant.

Route by artifact kind: Import QTI assessmentItem resources as question and QTI assessmentTest resources as content_kind=test, assessment_role=form through the QTI package endpoint. Author test_spec, test_bank, and article/video as drafts through the Alpha item/version/graph endpoints, then publish each exact immutable version through the governed publication endpoint. Video first uses the narrow first-party Incept media handoff and exact-version interactive_video composition. The generic publish endpoint intentionally does not accept question or form artifacts. The auth asymmetry is deliberate: Content semantically parses and receipts standardized QTI package materialization, while authored graphs, article bodies, and videos require the stronger publisher role and automatic kind-owned QC.

QTI question/form import: POST /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/imports/qti-package. Platform-issued tenant-scoped Bearer JWT with author:content; send application/zip and Idempotency-Key. A successful import materializes the returned exact QTI versions as published and trusted with Content-owned receipts.

test_spec/test_bank/article/video publication: POST /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items/{contentId}/publish. Platform-issued tenant-scoped Bearer JWT with publish:content and a service, reviewer, or operator role; send Idempotency-Key and body {"content_version_id":"{contentVersionId}"}.

Trust readback: GET /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items/{contentId}/trust.

Exact-version eligibility readback: GET /content/alpha/implementation/api/tenants/{tenantId}/alpha/content/items/{contentId}/versions/{contentVersionId}/release-eligibility?producer_surface={producerSurface}. Require the exact version readback to return matching content_id/content_version_id, trust_status trusted or degraded, serveable=true, release_eligible=true, and problem_code=null. release_eligible is exactly serveable; producer_surface is query-only compatibility, not caller evidence.

Trust boundary: Never POST or PATCH trust_status, a verdict, or an evidence URL. Content computes trust and the exact-version QC receipt. A later version cannot inherit an earlier receipt.

Failure and turnaround: Authorized import/publication is synchronous. A failed QC check changes no lifecycle, trust, graph, receipt, or fresh idempotency claim; correct the graph and retry with a new key. If the integrator token lacks the documented role/scope, request that narrow tenant credential through Platform credential onboarding; the repository defines no credential-provisioning SLA and there is no content-by-content owner approval queue.