Driving Course Desk from your own code

{
  "task": "outcomes",
  "brief": "Course: Practical Data Analysis with Python\nAudience: analysts who already use spreadsheets daily\nLevel: working\nShape: 6 weekly sessions, 90 minutes live each\nPrerequisites: comfortable with formulas; no programming assumed\n\nModules\nm1. Why notebooks (90m)\nm2. Tables in pandas (90m)\nm3. Cleaning messy data (90m)\nm4. Grouping and joining (90m)\nm5. Charts that answer a question (90m)\nm6. Capstone clinic (90m)\n\nObjectives\n- Understand pandas\n- Be familiar with data cleaning\n- Produce a chart from a real dataset\n\nAssessment\nWeekly exercises 40%, capstone notebook 60%",
  "brief_clipped": 0,
  "objectives": "Choose an appropriate join for a two-table question\nExplain one cleaning decision to a non-analyst",
  "focus": "",
  "level": "working",
  "delivery": "live-online",
  "rigor": "strict",
  "item_count": 12,
  "notes": "The cohort is internal; attendance is mandatory but graded pass/fail.",
  "upstream": "",
  "prescan": {
    "readable": true,
    "meta": { "title": "Practical Data Analysis with Python", "level": "working", "sessions": 6 },
    "schedule": { "sessions": 6, "minutes_each": 90, "total_minutes": 540 },
    "budget": { "contact_minutes": 540, "claimed_minutes": 540, "slack_minutes": 0 },
    "bloom": { "remember": 0, "understand": 2, "apply": 1, "analyze": 0, "evaluate": 0, "create": 0 },
    "stats": { "chars": 812, "lines": 24, "modules": 6, "objectives": 3 },
    "modules": [
      { "id": "m1", "title": "Why notebooks", "minutes": 90 },
      { "id": "m3", "title": "Cleaning messy data", "minutes": 90 }
    ],
    "objectives": [
      { "id": "o1", "text": "Understand pandas", "verb": "understand", "bloom": "understand", "measurable": false },
      { "id": "o3", "text": "Produce a chart from a real dataset", "verb": "produce", "bloom": "create", "measurable": true }
    ],
    "assessments": [
      { "id": "a1", "name": "Weekly exercises", "weight": 40 },
      { "id": "a2", "name": "Capstone notebook", "weight": 60 }
    ],
    "alignment": { "objectives_with_assessment": 1, "objectives_without_assessment": 2 },
    "signals": { "has_prerequisites": true, "has_assessment_weights": true, "weights_sum": 100 },
    "sampling": { "method": "full", "coverage": 1.0 },
    "negative_notes": ["No accessibility or accommodation statement found in the brief."],
    "flags": [
      {
        "flag_id": "f1",
        "rule": "unmeasurable_verb",
        "severity": "high",
        "confidence": "high",
        "scope": "objective",
        "target": "o1",
        "message": "\"Understand\" cannot be observed or scored.",
        "evidence": "- Understand pandas"
      },
      {
        "flag_id": "f2",
        "rule": "no_slack_in_budget",
        "severity": "medium",
        "confidence": "unknown",
        "scope": "schedule",
        "target": "all",
        "message": "Claimed activity minutes equal contact minutes exactly; nothing is left for transitions.",
        "evidence": "6 x 90m = 540m contact, 540m claimed"
      }
    ]
  }
}

{
  "task": "syllabus",
  "brief": "Course: Practical Data Analysis with Python\nAudience: analysts who already use spreadsheets daily\nShape: 6 weekly sessions, 90 minutes live each\n... (the same brief as above) ...",
  "brief_clipped": 0,
  "objectives": "",
  "focus": "",
  "level": "working",
  "delivery": "live-online",
  "rigor": "standard",
  "item_count": 12,
  "notes": "Week 4 falls on a public holiday and has to be async.",
  "upstream": "# Learning outcomes\n\n1. Load a CSV into a pandas DataFrame and report its shape...\n",
  "prescan": {
    "readable": true,
    "meta": { "title": "Practical Data Analysis with Python", "sessions": 6 },
    "schedule": { "sessions": 6, "minutes_each": 90, "total_minutes": 540 },
    "budget": { "contact_minutes": 540, "claimed_minutes": 540, "slack_minutes": 0 },
    "bloom": {},
    "stats": { "modules": 6, "objectives": 5 },
    "modules": [{ "id": "m1", "title": "Why notebooks", "minutes": 90 }],
    "objectives": [],
    "assessments": [],
    "alignment": {},
    "signals": {},
    "sampling": {},
    "negative_notes": [],
    "flags": [
      {
        "flag_id": "f2",
        "rule": "no_slack_in_budget",
        "severity": "medium",
        "confidence": "unknown",
        "scope": "schedule",
        "target": "all",
        "message": "Claimed activity minutes equal contact minutes exactly.",
        "evidence": "6 x 90m = 540m contact, 540m claimed"
      }
    ]
  }
}

{
  "task": "lesson",
  "brief": "Course: Practical Data Analysis with Python\n...\nm3. Cleaning messy data (90m)\n...",
  "brief_clipped": 0,
  "objectives": "Repair a column of mixed date formats and justify the choice",
  "focus": "m3",
  "level": "working",
  "delivery": "live-online",
  "rigor": "standard",
  "item_count": 12,
  "notes": "Breakout rooms are available. Cohort of 18, so plan for pairs.",
  "upstream": "",
  "prescan": {
    "readable": true,
    "meta": { "title": "Practical Data Analysis with Python" },
    "schedule": { "sessions": 6, "minutes_each": 90, "total_minutes": 540 },
    "budget": { "contact_minutes": 90, "claimed_minutes": 90, "slack_minutes": 0 },
    "bloom": {},
    "stats": { "modules": 6 },
    "modules": [{ "id": "m3", "title": "Cleaning messy data", "minutes": 90 }],
    "objectives": [],
    "assessments": [],
    "alignment": {},
    "signals": { "focus_resolved": true },
    "sampling": { "method": "module", "coverage": 1.0 },
    "negative_notes": [],
    "flags": []
  }
}

{
  "task": "assess",
  "brief": "Course: Practical Data Analysis with Python\n...\nAssessment\nWeekly exercises 40%, capstone notebook 60%",
  "brief_clipped": 0,
  "objectives": "Choose an appropriate join for a two-table question\nExplain one cleaning decision to a non-analyst",
  "focus": "",
  "level": "working",
  "delivery": "live-online",
  "rigor": "strict",
  "item_count": 12,
  "notes": "Grading is pass/fail overall but we still want per-criterion feedback.",
  "upstream": "# Syllabus\n\n## Session 3 - Cleaning messy data (90m)\n...",
  "prescan": {
    "readable": true,
    "meta": { "title": "Practical Data Analysis with Python" },
    "schedule": {},
    "budget": {},
    "bloom": { "understand": 2, "apply": 1, "create": 1 },
    "stats": { "objectives": 5, "assessments": 2 },
    "modules": [],
    "objectives": [
      { "id": "o5", "text": "Explain one cleaning decision to a non-analyst", "bloom": "understand" }
    ],
    "assessments": [
      { "id": "a1", "name": "Weekly exercises", "weight": 40 },
      { "id": "a2", "name": "Capstone notebook", "weight": 60 }
    ],
    "alignment": { "objectives_with_assessment": 3, "objectives_without_assessment": 2 },
    "signals": { "has_rubric": false, "weights_sum": 100 },
    "sampling": {},
    "negative_notes": ["No rubric of any kind was found in the brief."],
    "flags": [
      {
        "flag_id": "f7",
        "rule": "objective_without_evidence",
        "severity": "high",
        "confidence": "high",
        "scope": "alignment",
        "target": "o5",
        "message": "Nothing in the assessment plan would evidence this objective.",
        "evidence": "Weekly exercises 40%, capstone notebook 60%"
      }
    ]
  }
}

{
  "task": "quiz",
  "brief": "Course: Practical Data Analysis with Python\n...\nm4. Grouping and joining (90m)\n...",
  "brief_clipped": 0,
  "objectives": "Choose an appropriate join for a two-table question",
  "focus": "Grouping and joining",
  "level": "working",
  "delivery": "async",
  "rigor": "standard",
  "item_count": 16,
  "notes": "Delivered in an LMS that supports MCQ, true/false and matching only.",
  "upstream": "",
  "prescan": {
    "readable": true,
    "meta": { "title": "Practical Data Analysis with Python" },
    "schedule": {},
    "budget": {},
    "bloom": { "apply": 2, "analyze": 1 },
    "stats": { "modules": 6, "objectives": 5 },
    "modules": [{ "id": "m4", "title": "Grouping and joining", "minutes": 90 }],
    "objectives": [],
    "assessments": [],
    "alignment": {},
    "signals": { "focus_resolved": true, "item_count_clamped": false },
    "sampling": { "method": "module", "coverage": 1.0 },
    "negative_notes": [],
    "flags": [
      {
        "flag_id": "f11",
        "rule": "module_has_no_objective",
        "severity": "medium",
        "confidence": "high",
        "scope": "module",
        "target": "m4",
        "message": "No stated objective belongs to the focused module.",
        "evidence": "m4. Grouping and joining (90m)"
      }
    ]
  }
}

// success
{ "data": { "job_id": "job_9f2c...", "status": "queued" } }

// failure
{ "error": { "code": "VALIDATION_ERROR", "message": "task must be one of outcomes, syllabus, lesson, assess, quiz" } }

# Every call in this guide uses these two values.
BASE="https://api.skillsafe.ai/v1/app-api"
TOKEN="YOUR_TOKEN"      # Replace "YOUR_TOKEN" with a token from /tokens.html

# The envelope is the same on every endpoint:
#   success -> {"data": { ... }}
#   failure -> {"error": {"code": "...", "message": "..."}}
#
# There is no X-App-Slug header on any endpoint. Do not add one.
call() { curl -s -X "$1" "$BASE$2" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" ${3:+-d "$3"}; }

# A guest token needs NO Authorization header. The body key is "slug".
curl -s -X POST "$BASE/guest" \
  -H "Content-Type: application/json" \
  -d '{"slug": "course-desk"}'

# -> {"data":{"token":"aut_...","subject_type":"guest", ...}}
#
# For a metered run, take a personal token instead:
#   https://course-desk.skillsafe.ai/tokens.html

curl -s "$BASE/me" -H "Authorization: Bearer $TOKEN"

# -> {"data":{"subject_type":"user","username":"...","credits":123456}}
# subject_type is "guest" or "user". Only a "user" can run a lane.

# /estimate is FREE. It creates no job and charges nothing.
# The body IS the input object - it is not wrapped in anything.
curl -s -X POST "$BASE/estimate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"task":"outcomes","brief":"Course: Practical Data Analysis with Python\n...","brief_clipped":0,"objectives":"","focus":"","level":"working","delivery":"live-online","rigor":"strict","item_count":12,"notes":"","upstream":"","prescan":{"readable":true,"flags":[]}}'

# -> {"data":{"model":"gpt-5.6-terra","model_alias":"gpt-terra",
#      "markup_bps":1000,"hold_credits":2900,"min_credits":400,
#      "sponsor_enabled":false}}
#
# hold_credits is RESERVED, not charged. It prices the full output cap; the
# actual charge is usually far lower. Estimate each lane separately.
#
# WRONG: -d '{"input": {"task": "outcomes", ...}}'   <- VALIDATION_ERROR
# WRONG: -H "X-App-Slug: course-desk"                <- no such header

# Metered. The body is still the bare input object.
# Idempotency-Key = lane + input + attempt, hashed. Reuse it on a retry.
KEY="course-desk:outcomes:$(printf %s "$INPUT" | shasum | cut -c1-16):1"

JOB=$(curl -s -X POST "$BASE/run" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT" | python3 -c 'import json,sys;print(json.load(sys.stdin)["data"]["job_id"])')

# Poll until terminal. Two seconds is polite; do not tight-loop.
until curl -s "$BASE/jobs/$JOB" -H "Authorization: Bearer $TOKEN" \
  | grep -q '"status":"succeeded"'; do sleep 2; done

curl -s "$BASE/jobs/$JOB" -H "Authorization: Bearer $TOKEN"
# -> data.output is a STRING holding the JSON envelope described below.

# Server-sent events. Four event names: job, delta, done, error.
# Same bare input object, same Idempotency-Key header.
curl -N -X POST "$BASE/run-stream" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d "$INPUT"

# event: job
# data: {"job_id":"job_..."}
# event: delta
# data: {"text":"{\"lane\":\"outcomes\",\"title\":\"Learning outcomes..."}
# event: done
# data: {"job_id":"job_...","status":"succeeded","charged_credits":142,"output":"{...}"}

{
  "lane": "outcomes",
  "title": "string under 80 chars",
  "verdict": "one of the lane's verdicts",
  "headline": "one sentence under 160 chars",
  "summary": "two to four sentences",
  "checks":   [{"name": "", "value": "", "verdict": "good|weak|missing|risky|not-applicable", "note": ""}],
  "findings": [{"id": "", "severity": "critical|high|medium|low", "target": "", "quote": "", "why": "", "so_what": ""}],
  "rows":     [{"key": "", "label": "", "a": "", "b": "", "c": "", "note": ""}],
  "artifact": "the full document, Markdown",
  "artifact_json": {},
  "coverage_check": [{"flag_id": "", "status": "confirmed|cleared|not-applicable", "note": ""}],
  "questions": ["..."],
  "confidence": "high|medium|low"
}

// sent
"prescan": { "flags": [ {"flag_id": "f1", ...}, {"flag_id": "f2", ...} ] }

// returned - exactly these two ids, exactly once each
"coverage_check": [
  { "flag_id": "f1", "status": "confirmed",
    "note": "\"Understand pandas\" is rewritten as objective o1 with an observable verb." },
  { "flag_id": "f2", "status": "not-applicable",
    "note": "The outcomes lane does not schedule time, so the budget flag is left to the syllabus lane." }
]