Wire the Bank API. Know exactly when a bank is assignable.

Token to assignable bank

Prerequisites: a Platform3 Content test_spec ID and a signed tenant JWT whose mapped scopes include bank:write and bank:read. The API reads tenant identity from the verified token—never from the request body. Run this flow from your authenticated backend; a successful create returns an operation to poll, not a bank that is ready immediately.

export ALPHATEST_BANK_URL="https://alphatest-andymontgomery-9773s-projects.vercel.app/bank/integrator_api/implementation/api"
export ALPHATEST_TOKEN="<tenant-jwt>"
export SPEC_ID="<content-test-spec-uuid>"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ALPHATEST_TOKEN" \
  "$ALPHATEST_BANK_URL/v1/bank-operations?limit=1" | jq

HTTP_STATUS="$(curl --silent --show-error \
  -X POST "$ALPHATEST_BANK_URL/v1/bank-generations" \
  -H "Authorization: Bearer $ALPHATEST_TOKEN" \
  -H "Idempotency-Key: acmetest-g5-math-forms-001" \
  -H "Content-Type: application/json" \
  --data "{\"specId\":\"$SPEC_ID\",\"bankMode\":\"same_blueprint_fixed_forms\",\"formCount\":5}" \
  --output /tmp/alphatest-bank-response.json \
  --write-out '%{http_code}')"

case "$HTTP_STATUS" in
  202) export OPERATION_ID="$(jq -er '.operationId' /tmp/alphatest-bank-response.json)" ;;
  424) jq -e '.code == "dependency_contract_unavailable" and (.operationId == null)' /tmp/alphatest-bank-response.json >/dev/null && jq '{code,dependency,capability,sourceUrl,probeResult,requestId,traceId}' /tmp/alphatest-bank-response.json >&2; exit 1 ;;
  *) cat /tmp/alphatest-bank-response.json >&2; exit 1 ;;
esac

while :; do
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $ALPHATEST_TOKEN" \
    --dump-header /tmp/alphatest-bank-poll-headers \
    --output /tmp/alphatest-bank-operation.json \
    "$ALPHATEST_BANK_URL/v1/bank-operations/$OPERATION_ID"
  RESPONSE="$(cat /tmp/alphatest-bank-operation.json)"
  STATUS="$(jq -r '.status' <<<"$RESPONSE")"
  ASSIGNABLE="$(jq -r '.assignable' <<<"$RESPONSE")"
  printf 'bank operation: %s\n' "$STATUS"
  case "$STATUS:$ASSIGNABLE" in
    ready:true) jq '.result | {bankId, forms, adaptiveSelection}' <<<"$RESPONSE"; break ;;
    ready:*|ready_with_gaps:*|failed:*|cancelled:*) jq '{status,assignable,progress,manifestUrl}' <<<"$RESPONSE"; exit 1 ;;
    *) RETRY_AFTER="$(awk 'tolower($1)=="retry-after:" {gsub("\\r", "", $2); print $2}' /tmp/alphatest-bank-poll-headers | tail -1)"; sleep "${RETRY_AFTER:-5}" ;;
  esac
done

MANIFEST_URL="$(jq -er '.manifestUrl' /tmp/alphatest-bank-operation.json)"
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $ALPHATEST_TOKEN" \
  --dump-header /tmp/alphatest-bank-manifest-headers \
  --output "$OPERATION_ID-manifest.json" \
  "$ALPHATEST_BANK_URL$MANIFEST_URL"

jq '{manifestHash, gapCount:(.gaps|length), adaptivePool}' \
  "$OPERATION_ID-manifest.json"

202 and typed-424 contract: dependency readiness · Runtime readiness: BANK-ITD-003 · Release proof: BANK-ITD-016

Fixed forms are certified; adaptive and public legacy admission are closed

Admission is capability-specific. Fixed generation has the published SAME_BLUEPRINT_FIXED_FORMS-2026-07-21 owner receipt. Adaptive remains closed until a current immutable replay proves its QTI root, ordered members, and Content-owned KC relationships. Legacy is verification-only: conformance must read the governed collection and reconcile all 17 aliases without any owner mutation.

Exact gates: Incept generation, QTI ingest, Content registration, legacy alias proof · Fields: 424 Problem extension

One observable operation

Fixed-form requests may return 202 and enter the generated-bank lifecycle. Adaptive and public legacy requests remain typed-424 before admission. Legacy immutable conformance uses a distinct owner-read chain and can terminate ready only as a non-assignable, zero-mutation alias proof.

Contract: BANK-ITD-002 · Fields: BankOperation

Use the shape that matches your bank

Bearer JWT, tenant-scoped by default

Every route requires a signed, unexpired JWT with sub, role, tenantId, iat, and exp. Role-to-scope mapping must grant bank:read for GETs and bank:write for POSTs. A compatibility X-Timeback-Tenant header, if sent, must exactly match the verified claim.

Decision: BANK-AXIS-006 · Tenant routing: BANK-AXIS-009

One stable problem shape

By contract, every non-2xx response uses application/problem+json with stable type, title, status, safe detail, code, requestId, traceId, and optional field/upstream error arrays. A create-route 424 also carries the typed dependency-preflight fields. Log request and trace IDs; do not branch on human-readable detail.

{
  "type": "https://api.alphatest.app/problems/bank/dependency_contract_unavailable",
  "title": "Dependency contract unavailable",
  "detail": "Adaptive bank generation cannot be admitted until tenant-aligned QTI authority and adaptive-pool conformance are certified.",
  "status": 424,
  "code": "dependency_contract_unavailable",
  "requestId": "req_01JZBANK000000000000000001",
  "traceId": "trace_01JZBANK00000000000001",
  "dependency": "qti",
  "capability": "register_adaptive_pool",
  "sourceUrl": "https://platform3-andymontgomery-9773s-projects.vercel.app/qti/1edtech/customer_website",
  "probeResult": {"status":403,"code":"forbidden","checkedAt":"2026-07-20T15:13:34.339Z"}
}

Retry GETs after transient 429/5xx responses. Retry POSTs only with the same idempotency key and byte-equivalent semantic request. For the current 424, use dependency and capability to identify the exact uncertified seam; do not retry until that capability is certified. Honor Retry-After. See the endpoint-by-endpoint error matrix.

“Ready” is a proof-backed state

When an admitted operation reaches a terminal state, the manifest binds the request/spec version, converter version, source and QTI hashes, CASE resolutions, slot verdicts, misconception-tagged distractor checks, Platform3 score probes, owner read-back, gaps, timings, and safe upstream trace IDs. Adaptive manifests add the QTI-owned pool and Content-owned KC reconciliation; legacy manifests add legacyProof with the governed collection, 17 aliases, and zero-mutation assertion. A manifest contains hashes and references—not prompts, item bodies, answer keys, learners, responses, attempts, or mastery records.

Manifest definition: EvidenceManifest · Adaptive fields: adaptivePool · Legacy fields: legacyProof · Architecture: distractor verification, adaptive receipt, audit and conformance evidence

No quiet downgrade, no local substitute

If Incept cannot generate a requested interaction, the converter cannot represent it, Platform3 cannot score it, or a selected-response distractor lacks a distinct named misconception, AlphaTest records the exact slot and boundary, links an upstream Issue when available, and names the proof metric for closure. It never swaps in an easier item, invents a misconception tag, or authors an item locally. Reports-owned weak-item revision orders trigger a new Incept generation and full verification chain; only a verified immutable replacement rotates into Content membership, with the old version retained for audit and in-flight administrations. Read the append-only rotation decision.

Thin by design

The approved implementation contract requires a server-only datastore behind the authenticated API. Service-role credentials must never reach clients, every local query must begin with the verified tenantId, and missing and cross-tenant identifiers must be indistinguishable. Upstream credentials must be least-privilege server credentials.

Security model: BANK-ITD-015 · Persistence fields: bank_operation

Adopt certified fixed forms; hold adaptive and public legacy

The approved owner receipt opens fixed-form generation only. Adaptive and legacy remain independent proof branches:

• Fixed certified: SAME_BLUEPRINT_FIXED_FORMS-2026-07-21 publishes the owner-backed fixed receipt. Each returned operation still must be ready/assignable=true with a complete manifest before assignment.
• Adaptive closed: new public creates return typed 424. Certification requires a ready/assignable/zero-gap immutable replay whose manifest has a stable non-null adaptivePool, QTI-owned member order, and Content-owned primary KC reconciliation.
• Security contract: anonymous access rejects; tenant identity is derived from the verified JWT; missing and cross-tenant resources share the same 404 shape.
• Legacy verification-only: public admission remains typed-424. Immutable conformance loads timeback-alphatest-legacy-forms-v1 and must prove exactly 17 aliases with bankId=null, ownerMutationCount=0, and assignable=false. It never registers membership.

Fail-closed rule still applies. Any request whose own dependency preflight fails returns typed 424 with no operation. Any admitted operation that fails verification stays non-assignable and exposes its manifest. No fixture, copied standard, local scorer, local item, or local Content-membership substitute may produce ready.

Conformance decisions: BANK-AXIS-010 · BANK-ITD-016 release gate · Contract examples: required and conditional shapes

Stable under /v1

Additive optional response fields and new terminal gap codes are compatible; clients must ignore unknown response fields and tolerate unknown response enum values. Removal, renaming, changed meaning, or narrowing requires a new major path. Unknown request fields and enum values reject.

Compatibility and enum contract: enumerations and compatibility rules