Assign. Launch QTI. Get verified Results.

Set credentials and Platform3 IDs

Copyset -euo pipefail
: "${ALPHATEST_JWT:?Set a Platform JWT with role integrator or reviewer}"
: "${QTI_TEST_ID:?Set the published Content fixed-form bank id accepted by QTI}"
: "${CONTENT_TEST_SPEC_ID:?Set its Content test_spec id}"
: "${ONEROSTER_CLASS_ID:?Set an active OneRoster class sourcedId}"
: "${OPENS_AT:?Set an RFC 3339 UTC instant before this run}"
: "${CLOSES_AT:?Set an RFC 3339 UTC instant after this run}"

BASE_URL="https://alphatest-administration.vercel.app/api"
AUTH="Authorization: Bearer ${ALPHATEST_JWT}"
JSON="Content-Type: application/json"

JWT claims · TestRef · target fields · ITD-007

Create one mastery-gate administration

Expected: 202 Accepted, a body with id, and a Location header after the fixed-gate predicate passes. A reachable bank/spec/member mismatch returns pre-effect 422 test-not-assignable; its safe diagnostic detail names the first failed predicate in the documented six-step order. Do not retry unchanged IDs. Reuse the key only when retrying this logical create.

CopyCREATE_KEY="acmetest-${ONEROSTER_CLASS_ID}-fall-gate-v1"
jq -n --arg qti "$QTI_TEST_ID" --arg spec "$CONTENT_TEST_SPEC_ID" \
  --arg class "$ONEROSTER_CLASS_ID" --arg opens "$OPENS_AT" --arg closes "$CLOSES_AT" '{
  test:{qtiTestId:$qti,contentTestSpecId:$spec,testKind:"mastery_gate"},
  target:{type:"class",oneRosterSourcedId:$class},
  window:{opensAt:$opens,closesAt:$closes},
  timing:{timeLimitSeconds:5400},
  retakes:{maxAttempts:3,parallelFormRotation:"different_form_required"},
  accommodations:{default:{timeMultiplier:1},candidateOverrides:[]}
}' >/tmp/alphatest-create.json

curl --fail-with-body --silent --show-error \
  --dump-header /tmp/alphatest-create.headers \
  --output /tmp/alphatest-create.out \
  --request POST "${BASE_URL}/v1/administrations" \
  --header "$AUTH" --header "$JSON" \
  --header "Idempotency-Key: ${CREATE_KEY}" \
  --data-binary @/tmp/alphatest-create.json

test "$(awk 'NR==1{print $2}' /tmp/alphatest-create.headers)" = "202"
ADMIN_ID="$(jq -er '.id' /tmp/alphatest-create.out)"
printf 'Administration: %s\n' "$ADMIN_ID"

create endpoint · request fields · 422 diagnostic order · idempotency · ITD-014 · ITD-037

Poll provisioning and authorize each launch

The candidates collection intentionally omits raw session references. Call the per-candidate launch action inside the window to receive a deliverySessionRef, then pass it unchanged to your QTI player. If bounded upstream fan-out partially fails, resume only failed candidates.

CopyRESUME_COUNT=0
while :; do
  ADMIN="$(curl --fail-with-body --silent --show-error --header "$AUTH" \
    "${BASE_URL}/v1/administrations/${ADMIN_ID}")"
  STATUS="$(jq -r '.status' <<<"$ADMIN")"
  case "$STATUS" in
    scheduled|open) break ;;
    provisioning_with_errors)
      ((RESUME_COUNT+=1)); [[ "$RESUME_COUNT" -le 5 ]] || { jq . <<<"$ADMIN"; exit 1; }
      curl --fail-with-body --silent --show-error \
        --request POST "${BASE_URL}/v1/administrations/${ADMIN_ID}/provision" \
        --header "$AUTH" --header "$JSON" \
        --header "Idempotency-Key: provision-${ADMIN_ID}-${RESUME_COUNT}" \
        --data '{}' >/tmp/alphatest-provision.out
      sleep 2 ;;
    provisioning) sleep 2 ;;
    *) printf 'Unexpected status: %s\n' "$STATUS" >&2; exit 1 ;;
  esac
done

: >/tmp/alphatest-launches.ndjson
CURSOR=""
while :; do
  CANDIDATE_URL="${BASE_URL}/v1/administrations/${ADMIN_ID}/candidates?limit=100"
  if [[ -n "$CURSOR" ]]; then
    CANDIDATE_URL="${CANDIDATE_URL}&cursor=$(jq -rn --arg value "$CURSOR" '$value|@uri')"
  fi
  PAGE="$(curl --fail-with-body --silent --show-error --header "$AUTH" "$CANDIDATE_URL")"
  while IFS= read -r CANDIDATE_ID; do
    CANDIDATE_PATH="$(jq -rn --arg value "$CANDIDATE_ID" '$value|@uri')"
    LAUNCH_KEY="launch-${ADMIN_ID}-${CANDIDATE_ID}-1"
    curl --fail-with-body --silent --show-error \
      --request POST \
      --header "$AUTH" --header "Idempotency-Key: ${LAUNCH_KEY}" \
      "${BASE_URL}/v1/administrations/${ADMIN_ID}/candidates/${CANDIDATE_PATH}/launch" \
      | tee -a /tmp/alphatest-launches.ndjson | jq -er \
        '{oneRosterSourcedId,deliverySessionRef,timeLimitSeconds,runtimeEnforced}'
  done < <(jq -r '.data[].oneRosterSourcedId' <<<"$PAGE")
  [[ "$(jq -r '.hasMore' <<<"$PAGE")" == "true" ]] || break
  CURSOR="$(jq -er '.nextCursor' <<<"$PAGE")"
done

Expected launch status is 200. A pre-window call returns 403 launch-not-open; at or after close it returns 410 launch-window-ended, even for a stored idempotent replay.

candidate paging · launch endpoint · replay precedence · ITD-031

Close after QTI submission; poll to verified Results

Submit each launched attempt through your existing QTI player first. Close returns 409 close-not-ready while any launched candidate lacks a submitted latest attempt or that attempt is still in progress; once every launched candidate has submitted, it returns 202.

Your client sends only the strict {} body, its Platform JWT, and the idempotency key. Server-side, AlphaTest reads the QTI score, writes one Results record, and exact-reads by qtiAttemptId; it exposes scored only after the QTI, Content, administration, test-kind, subject, and Results correlations agree exactly. Platform3 service credentials never enter this request or its response.

CopyCLOSE_KEY="close-${ADMIN_ID}-v1"
curl --fail-with-body --silent --show-error \
  --dump-header /tmp/alphatest-close.headers \
  --output /tmp/alphatest-close.out \
  --request POST "${BASE_URL}/v1/administrations/${ADMIN_ID}/close" \
  --header "$AUTH" --header "$JSON" \
  --header "Idempotency-Key: ${CLOSE_KEY}" --data '{}'
test "$(awk 'NR==1{print $2}' /tmp/alphatest-close.headers)" = "202"
test "$(jq -r '.status' /tmp/alphatest-close.out)" = "closing"

while :; do
  ADMIN="$(curl --fail-with-body --silent --show-error --header "$AUTH" \
    "${BASE_URL}/v1/administrations/${ADMIN_ID}")"
  case "$(jq -r '.status' <<<"$ADMIN")" in
    scored) break ;;
    close_failed) jq . <<<"$ADMIN"; exit 1 ;;
    closing) sleep 2 ;;
    *) jq . <<<"$ADMIN"; exit 1 ;;
  esac
done

: >/tmp/alphatest-results.ndjson
CURSOR=""
while :; do
  RESULTS_URL="${BASE_URL}/v1/administrations/${ADMIN_ID}/candidates?limit=100"
  if [[ -n "$CURSOR" ]]; then
    RESULTS_URL="${RESULTS_URL}&cursor=$(jq -rn --arg value "$CURSOR" '$value|@uri')"
  fi
  PAGE="$(curl --fail-with-body --silent --show-error --header "$AUTH" "$RESULTS_URL")"
  jq -ce '.data[] | select(.state == "scored" and has("resultRecordRef"))' \
    <<<"$PAGE" >>/tmp/alphatest-results.ndjson
  test "$(jq '.data | length' <<<"$PAGE")" = \
       "$(jq '[.data[] | select(.state == "scored" and has("resultRecordRef"))] | length' <<<"$PAGE")"
  [[ "$(jq -r '.hasMore' <<<"$PAGE")" == "true" ]] || break
  CURSOR="$(jq -er '.nextCursor' <<<"$PAGE")"
done
test -s /tmp/alphatest-results.ndjson
jq -r '[.oneRosterSourcedId,.resultRecordRef] | @tsv' /tmp/alphatest-results.ndjson

close endpoint · close semantics · resultRecordRef · ITD-030