API Reference

Base URL: https://api.qlmdev.com — All endpoints return JSON. All requests require Content-Type: application/json.

Authentication

Include your API key in the Authorization header on every request:

Header

Authorization: Bearer qlm_live_YOUR_API_KEY

The demo endpoint (/v1/demo/compare) does not require authentication.

Assessment Engine

Core question selection and personalized session management.

POST /v1/optimize Select optimal items via personalized question selection

Given a current skill state and previously administered items, returns the next-best set of items to administer. Returns ranked items.

{
  "item_bank_id": "string",        // Required. Your item bank ID.
  "skill_levels": [0.0],       // Required. Current skill levels (array of floats).
  "items_administered": ["string"], // Items already given (array of item IDs).
  "n_select": 5,                  // Number of items to select. Default: 5.
  "constraints": {                 // Optional constraints.
    "max_time": 300,              // Max total time in seconds.
    "content_balance": true,      // Enforce content balancing.
    "exclude_items": ["string"]   // Items to exclude.
  }
}

{
  "job_id": "string",
  "status": "completed",
  "selected_items": [
    {"item_id": "string", "rank": 1}
  ],
  "timestamp": "ISO 8601"
}

Try it

// Response will appear here

POST /v1/sessions Create a personalized assessment session

Creates a new personalized session. The engine selects questions and tracks completion.

{
  "organization_id": "string",
  "item_bank_id": "string",
  "domain": "string",          // clinical | cyber | financial | education | ...
  "config": {
    "max_items": 30,
    "completion_threshold": 0.95
  }
}

{
  "session_id": "string",
  "status": "active",
  "recommended_items": [
    {"item_id": "string", "rank": 1}
  ]
}

Try it

// Response will appear here

POST /v1/sessions/{id}/responses Submit responses and get next items

Submit one or more item responses. Returns next items to administer and completion state.

{
  "responses": [
    {
      "item_id": "string",
      "value": 0               // Integer response value
    }
  ]
}

{
  "next_items": [
    {"item_id": "string", "rank": 1}
  ],
  "confident": false
}

Try it

// Response will appear here

GET /v1/sessions/{id} Get session status and results

Retrieve the current state of a session including completion status.

{
  "session_id": "string",
  "status": "active",         // active | completed | terminated
  "confident": true
}

Try it

// Response will appear here

DELETE /v1/sessions/{id} Delete a session

Permanently delete a session and all associated data. This action cannot be undone.

{
  "deleted": true,
  "session_id": "string"
}

Try it

// Response will appear here

Domain Service

Specialized personalized sessions for domain-specific assessments. All domains use the same session endpoints with a different domain parameter.

Clinical Assessment

Personalized mental health screening, symptom severity measurement, and clinical outcome tracking. Validated against PHQ-9, GAD-7, and PCL-5 benchmarks.

Domain ID: clinical

Dimensions: Depression, Anxiety, PTSD, Substance Use, Functional Impairment

Create clinical session

POST /v1/sessions
{
  "domain": "clinical",
  "item_bank_id": "ib_clinical_v2",
  "config": { "max_items": 25, "completion_threshold": 0.95 }
}

Cybersecurity Assessment

Personalized security posture evaluation, vulnerability awareness testing, and compliance screening.

Domain ID: cyber

Dimensions: Network Security, Application Security, Social Engineering, Incident Response, Compliance

Create cyber session

POST /v1/sessions
{
  "domain": "cyber",
  "item_bank_id": "ib_cyber_v1",
  "config": { "max_items": 30, "completion_threshold": 0.95 }
}

Financial Risk Assessment

Personalized financial literacy, risk tolerance, and compliance evaluation.

Domain ID: financial

Dimensions: Risk Tolerance, Financial Literacy, Regulatory Knowledge, Portfolio Management, Market Awareness

Create financial session

POST /v1/sessions
{
  "domain": "financial",
  "item_bank_id": "ib_fin_v1",
  "config": { "max_items": 20, "completion_threshold": 0.95 }
}

Educational Assessment

Personalized placement testing, formative assessment, and mastery-based progression.

Domain ID: education

Dimensions: Content Mastery, Problem Solving, Critical Thinking, Application

Create education session

POST /v1/sessions
{
  "domain": "education",
  "item_bank_id": "ib_edu_v1",
  "config": { "max_items": 30, "completion_threshold": 0.95 }
}

HR & Talent Assessment

Personalized hiring screens, competency evaluation, and leadership assessment.

Domain ID: hr

Dimensions: Technical Skill, Communication, Leadership, Problem Solving, Culture Fit

Create HR session

POST /v1/sessions
{
  "domain": "hr",
  "item_bank_id": "ib_hr_v1",
  "config": { "max_items": 25, "completion_threshold": 0.95 }
}

Additional Domains

The same engine supports any domain. Additional pre-configured domains include:

Domain ID	Description	Typical Items
`compliance`	Regulatory compliance screening	20–35
`medical`	Medical knowledge assessment	25–40
`language`	Language proficiency testing	15–30
`safety`	Safety & hazard awareness	15–25
`personality`	Personality & behavioral traits	20–35

Curriculum Sequencing

Generate optimal learning paths from a curriculum with prerequisites and learner state.

POST /v1/sequence Compute an optimal curriculum sequence for a learner

Given a set of curriculum items with prerequisites and a learner's current mastery state, returns an ordered sequence optimized for the specified objective.

{
  "curriculum": [
    {
      "item_id": "string",
      "title": "string",
      "skills": ["string"],
      "prerequisites": ["string"],   // item_ids that must come first
      "difficulty": 0.5,
      "estimated_minutes": 30
    }
  ],
  "learner_state": {
    "skill_name": 0.0            // Current mastery per skill
  },
  "optimize_for": "efficiency"     // efficiency | mastery | engagement
}

{
  "job_id": "string",
  "sequence": [
    {"item_id": "string", "position": 1, "reason": "string"}
  ],
  "total_items": 12,
  "estimated_minutes": 360,
  "skills_covered": ["string"]
}

Tutoring Intelligence

Analyze student responses, generate targeted hints, and diagnose misconceptions.

POST /v1/tutor/analyze Analyze a student response and generate feedback

Submit a student response alongside the correct answer. Returns an analysis with explanation, misconception diagnosis, and a targeted hint.

{
  "item_id": "string",
  "correct_answer": "string",
  "student_answer": "string",
  "skill_id": "string",
  "difficulty": 0.5,
  "student_mastery": {
    "skill_name": 0.0
  }
}

{
  "is_correct": false,
  "explanation": "string",
  "misconception": "string",
  "hint": "string",
  "skill_gaps": ["string"],
  "suggested_next": "string",       // Suggested next item_id
  "difficulty_assessment": "too_hard", // too_easy | appropriate | too_hard
  "confidence": 0.87
}

Longitudinal Analytics

Track mastery trajectories over time, detect at-risk students, and compare cohorts.

GET /v1/analytics/trajectory/{student_id} Get a student's mastery trajectory over time

Returns the historical mastery trajectory for a student across all measured skills.

{
  "trajectory": [
    {
      "date": "ISO 8601",
      "skills": {"skill_name": 0.0},
      "confident": false
    }
  ],
  "skill_trends": {
    "skill_name": "improving"   // improving | stable | declining
  }
}

GET /v1/analytics/at-risk Identify at-risk students below a mastery threshold

Returns students whose mastery trend is declining or below the specified threshold. Query parameter: threshold (default 0.5).

{
  "at_risk_students": [
    {
      "external_user_id": "string",
      "trend": "declining",
      "risk_level": "high",          // low | medium | high
      "recommended_action": "string"
    }
  ]
}

Content Calibration

Submit your question bank for expert review, tagging, bias analysis, and difficulty calibration. Questions are reviewed by domain experts and returned with difficulty and quality parameters.

POST /v1/calibration/submit-bank Submit an item bank for calibration

Submit an item bank for expert review. Returns a job ID to track progress.

{
  "bank_id": "string",              // Required. Your item bank ID.
  "priority": "standard",           // "standard" | "express"
  "calibration_types": ["review", "tag", "bias", "difficulty"]  // Types of calibration requested.
}

{
  "job_id": "string",
  "estimated_completion": "ISO 8601",
  "estimated_cost_cents": 4500,
  "items_queued": 150
}

GET /v1/calibration/{job_id}/status Check calibration job progress

Returns the current progress of a calibration job including item counts and flagged items.

{
  "items_total": 150,
  "items_completed": 87,
  "items_passed": 82,
  "items_flagged": 5
}

GET /v1/calibration/pricing Get calibration pricing tiers

Returns available pricing tiers for item calibration services.

{
  "tiers": [
    {"type": "standard", "turnaround": "5 business days", "price_per_item_cents": 30},
    {"type": "express", "turnaround": "1 business day", "price_per_item_cents": 75}
  ]
}

Research Export

Create research studies and export anonymized data for analysis.

POST /v1/research/studies Create a research study definition

Define a research study with parameters for data collection, anonymization, and export scope.

{
  "name": "string",
  "item_bank_id": "string",
  "date_range": {
    "start": "ISO 8601",
    "end": "ISO 8601"
  },
  "anonymize": true
}

{
  "study_id": "string",
  "status": "created",
  "record_count": 0,
  "created_at": "ISO 8601"
}

GET /v1/research/studies/{id}/export Export study data in CSV or JSON format

Download anonymized study data. Query parameter: format (csv | json, default csv).

// Returns file download (Content-Type: text/csv or application/json)
// CSV columns: session_id, item_id, response, mastery_estimate, timestamp

Equivalence Toolkit

Run equivalence studies across item forms and generate accessibility compliance documentation.

POST /v1/equivalence/study Run an equivalence study between item forms

Compare two item bank forms for statistical equivalence. Returns agreement metrics and bias indicators.

{
  "form_a": "string",            // item_bank_id for form A
  "form_b": "string",            // item_bank_id for form B
  "method": "dif"               // dif | equating | concordance
}

{
  "study_id": "string",
  "equivalent": true,
  "agreement": 0.94,
  "flagged_items": ["string"],
  "report_url": "string"
}

POST /v1/equivalence/vpat/generate Generate a VPAT accessibility compliance report

Generates a Voluntary Product Accessibility Template report for an item bank.

{
  "item_bank_id": "string",
  "standard": "WCAG_2_1_AA"     // WCAG_2_1_AA | Section_508 | EN_301_549
}

{
  "vpat_id": "string",
  "status": "generated",
  "download_url": "string",
  "criteria_met": 42,
  "criteria_total": 50
}

Onboarding

Create organizations and upload item banks.

POST /v1/organizations Create an organization and get API key

Creates a new organization. Returns the API key (shown only once).

{
  "name": "string",          // Required. Organization name.
  "admin_email": "string",   // Required. Admin email.
  "tier": "free"             // Optional. free | growth | enterprise
}

{
  "organization_id": "string",
  "name": "string",
  "api_key": "string",        // Shown only once!
  "created_at": "ISO 8601",
  "tier": "free"
}

Try it

// Response will appear here

POST /v1/organizations/{id}/item-banks Upload an item bank

Upload items. Items can span multiple dimensions.

{
  "name": "string",
  "items": [
    {
      "id": "string",
      "difficulty": 0.5,      // 0-1 float
      "dimensions": ["algebra", "geometry"]
    }
  ]
}

{
  "item_bank_id": "string",
  "organization_id": "string",
  "items_loaded": 150,
  "dimensions": 3,
  "status": "ready"
}

Try it

// Response will appear here

Demo (No Auth Required)

Try the personalized selection engine without an API key.

POST /v1/demo/compare Compare QLM vs traditional item selection

Returns a side-by-side comparison of traditional sequential testing vs QLM-optimized selection. No authentication required.

{
  "item_bank_id": "ib_demo_001",
  "respondent_profile": {
    "skill_levels": [0.5, -0.2, 0.8]
  },
  "n_items": 15
}

Try it — no API key needed

// Response will appear here

Error Codes

All errors return a JSON body with error and message fields.

Status	Error Code	Description
200	-	Success
201	-	Created
400	`invalid_request`	Malformed JSON or missing required fields
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	API key lacks permission for this resource
404	`not_found`	Resource does not exist
409	`conflict`	Session already completed or terminated
422	`unprocessable`	Valid JSON but invalid parameters (e.g., skill level dimension mismatch)
429	`rate_limited`	Too many requests. Retry after the `Retry-After` header value.
500	`internal_error`	Server error. Contact support if persistent.

Error response example

{
  "error": "invalid_request",
  "message": "Invalid request.",
  "request_id": "req_abc123"
}