API Reference

AILAT API v1.0.1

An adaptive testing API that measures AI literacy across four dimensions. Create assessments, submit answers, and retrieve personalized results from your LMS, HR tool, or custom application.

Quick start Request an API token

Base URL

https://ailat.io/api/v1

Auth

Bearer token

Rate limit

100 req / min

Getting started

Overview

The AILAT API powers the AI Literacy Assessment Test — a psychometrically validated adaptive assessment. A single integration exposes 20-question sessions, real-time difficulty adaptation, evaluated open-ended responses, and a full results profile with a personalized learning path.

https://ailat.io/api/v1

Authentication

Every request requires a bearer token. Contact mail@founderly.com to obtain one.

Authorization: Bearer YOUR_API_TOKEN

Auth errors return a unified Authentication failed. response for all failure modes to prevent token enumeration.

Quick start

A typical integration follows five steps.

1
Create. POST /assessments — returns the first question.
2
Present. Render the returned question to the user.
3
Submit. POST /assessments/{id}/answers — the response includes the next question.
4
Repeat. Continue steps 2 – 3 until assessment_complete: true.
5
Fetch. GET /assessments/{id}/results — full literacy profile.

Phases

Phase	Questions	Description
Calibration	5	Mixed-difficulty baseline across all dimensions.
Adaptive	10	IRT-driven selection targeting the weakest area. Includes 2 open-ended.
Scenario	5	Industry-specific context with 1 open-ended capstone.

Core concepts

Assessment lifecycle

Sessions move through a small state machine. Sessions auto-pause after 30 minutes of inactivity; resume with a status update before submitting more answers.

created  ──▶  in_progress  ──▶  completed
                 │                ▲
                 ▼                │
              paused  ────────────┘
                 │
                 ▼
         pending_results  ──▶  completed  (on retry)

Status	Meaning
`in_progress`	Assessment is active and accepting answers.
`paused`	Paused by the user or automatically after 30 minutes of inactivity.
`completed`	All questions answered and results are available.
`pending_results`	All questions answered; results are still being generated.

Pending results: if results generation is still in progress, GET /results returns HTTP 202 with a Retry-After: 30 header.

HTTP status codes

Errors share a consistent shape. Check recovery_action for user-facing guidance.

Code	Meaning
`200`	Success.
`202`	Accepted — results are still being generated; retry after delay.
`400`	Bad request — invalid parameters, idle session, or completed assessment.
`401`	Unauthorized — invalid or missing token.
`403`	Forbidden — token lacks access to the requested resource.
`404`	Not found — assessment or resource does not exist.
`429`	Rate limited — check Retry-After header.
`500`	Server error.
`501`	Not implemented — feature planned for v1.1.
`503`	Service unavailable — retry in 30s.

{
  "success": false,
  "error": "ValidationError",
  "message": "Human-readable description",
  "details": { },
  "recovery_action": "What to do next"
}

Rate limits

100 requests per minute per API token. Exceeding the limit returns 429 with a Retry-After header. Use exponential backoff with jitter when retrying.

Header	Value
`X-RateLimit-Limit`	`100`
`X-RateLimit-Remaining`	Approximate remaining requests.

Endpoints

Each endpoint speaks JSON and returns the shape shown. {id} is the assessment identifier returned from the create call.

POST/assessments

Create assessment

Creates a new assessment and returns the first question.

Request

Field	Type	Required	Description
`industry`	enum	Yes	One of the industry values listed below.
`role`	string	Yes	User's professional role.
`motivation`	enum	No	One of the motivation values listed below.
`organization_id`	string	No	Organization identifier for analytics.
`user_id`	string	No	User identifier for tracking.

Response

{
  "success": true,
  "assessment_id": "asmt_abcdef123456",
  "status": "in_progress",
  "current_question": {
    "question_id": "Q1",
    "question_text": "...",
    "question_type": "multiple_choice",
    "options": {
      "A": "...",
      "B": "...",
      "C": "...",
      "D": "..."
    },
    "dimension": "CONCEPTUAL_KNOWLEDGE"
  },
  "progress": {
    "questions_completed": 0,
    "total_questions": 20,
    "percent_complete": 0
  }
}

Valid industry values

Value
`Academia & Education`
`Agriculture, Forestry & Fishing`
`Arts, Entertainment & Media`
`Construction & Real Estate`
`Energy & Utilities`
`Financial Services`
`Government & Public Sector`
`Healthcare & Social Services`
`Hospitality & Tourism`
`Information Technology`
`Legal Services`
`Manufacturing`
`Professional Services`
`Retail & Consumer Goods`
`Science & Research`
`Telecommunications`
`Transportation & Logistics`
`Wholesale & Distribution`
`General`

Valid motivation values

Value	Meaning
`Professional Development`	For current job role improvement
`Career Transition`	Moving to a new AI-related role
`Academic Learning`	For educational purposes
`Leadership`	For managing teams using AI
`Personal Interest`	General curiosity about AI
`Organizational Assessment`	Understanding team capabilities
`Certification`	Preparing for formal certification
`Required Training`	Mandated by organization

GET/assessments/{id}

Get assessment state

Returns the current question and progress. Use this to resume after a page reload.

Response headers: Cache-Control: no-store. Response shape matches the create call.

POST/assessments/{id}/answers

Submit answer

Submits an answer and returns the next question, or completion status.

Request

Field	Type	Required	Description
`question_id`	string	Yes	ID of the question being answered.
`answer`	string	Yes	A/B/C/D for multiple-choice, or free text for open-ended.
`response_time_ms`	number	No	Milliseconds spent answering (capped at 600,000).

Response

{
  "success": true,
  "is_correct": false,
  "correct_answer": "C",
  "explanation": "...",
  "next_question": { ... },
  "progress": { "questions_completed": 1, "total_questions": 20, "percent_complete": 5 },
  "assessment_complete": false
}

Idempotency

Re-submitting the same question_id with the same answer returns the cached result instead of an error. This makes network-timeout retries safe.

Open-ended response shape

{
  "success": true,
  "evaluation": {
    "overall_score": 0.85,
    "feedback": "Your explanation demonstrates excellent understanding..."
  },
  "next_question": { ... },
  "progress": { ... },
  "assessment_complete": false
}

Complete response

{
  "success": true,
  "is_correct": true,
  "correct_answer": "C",
  "explanation": "...",
  "assessment_complete": true,
  "results_url": "/v1/assessments/asmt_abcdef123456/results",
  "progress": { "questions_completed": 20, "total_questions": 20, "percent_complete": 100 }
}

PUT/assessments/{id}/status

Update assessment status

Pause or resume an assessment.

Request

Field	Type	Required	Description
`status`	string	Yes	"paused" or "in_progress".

Response

{
  "success": true,
  "assessment_id": "asmt_abcdef123456",
  "status": "paused",
  "resume_url": "/v1/assessments/asmt_abcdef123456",
  "expires_at": "2025-04-07T14:30:45Z"
}

completed and pending_results are system-managed and cannot be set manually.

GET/assessments/{id}/results

Get assessment results

Returns the full results of a completed assessment.

Response headers: Cache-Control: private, max-age=3600

Status-specific behavior

Assessment status	Behavior
`completed`	Returns results immediately.
`pending_results`	Attempts to generate results; returns `202` with `Retry-After: 30` if still pending.
Other statuses	Returns `400`.

Response

{
  "success": true,
  "assessment_id": "asmt_abcdef123456",
  "user_id": "user_xyz789",
  "organization_id": "org_abc123",
  "completed_at": "2025-04-05T15:15:12Z",
  "duration_minutes": 45,
  "overall_score": 76.5,
  "ai_literacy_level": 4,
  "level_details": {
    "title": "Critical Evaluator",
    "description": "Proficient understanding and skilled application of AI.",
    "indicators": [
      "Regularly applies AI tools to solve complex problems",
      "Can critically evaluate AI outputs",
      "Understands technical limitations of AI systems",
      "Considers ethical implications of AI use"
    ]
  },
  "dimension_scores": {
    "CONCEPTUAL_KNOWLEDGE": 85.0,
    "USE_APPLY_KNOWLEDGE": 75.0,
    "EVALUATE_CREATE_KNOWLEDGE": 70.0,
    "ETHICS_KNOWLEDGE": 65.0
  },
  "strengths": [ "Strong understanding of AI concepts and terminology" ],
  "growth_areas": [ "Enhance awareness of AI ethics and responsible use" ],
  "learning_path": {
    "focus_areas": [ "AI ethics", "Critical evaluation of AI outputs" ],
    "resources": [
      {
        "title": "AI Ethics: Principles for Professionals",
        "type": "course",
        "url": "https://example.com/ai-ethics",
        "relevance": "Addresses ethical considerations for AI applications"
      }
    ],
    "next_steps": [
      "Complete the AI Ethics course",
      "Apply evaluation frameworks to AI tools you currently use"
    ]
  },
  "answer_insights": {
    "average_response_time_ms": 45000,
    "fastest_dimension": "CONCEPTUAL_KNOWLEDGE",
    "slowest_dimension": "ETHICS_KNOWLEDGE",
    "consistent_errors": []
  }
}

GET/assessments/{id}/status

Get assessment status

Lightweight status check without the current question.

{
  "success": true,
  "assessment_id": "asmt_abcdef123456",
  "status": "in_progress",
  "user_id": "user_xyz789",
  "organization_id": "org_abc123",
  "created_at": "2025-04-05T13:15:12Z",
  "last_activity": "2025-04-05T13:25:42Z",
  "progress": { "questions_completed": 8, "total_questions": 20, "percent_complete": 40 },
  "expires_at": "2025-04-06T13:25:42Z"
}

GET/organizations/{organizationId}/results

Organization results

Aggregated analytics for an organization.

Response headers: Cache-Control: private, max-age=600

Query parameters

Field	Type	Required	Description
`time_period`	string	No	all_time (default), last_7_days, last_30_days, last_90_days, current_year.
`limit`	number	No	Results per page (1–500, default 100).
`cursor`	string	No	Pagination cursor from the previous response.

Response (abbreviated)

{
  "success": true,
  "organization_id": "org_abc123",
  "pagination": { "limit": 100, "next_cursor": "..." },
  "total_assessments": 25,
  "completed_assessments": 23,
  "average_score": 72.5,
  "average_level": 3.6,
  "completion_rate": 0.92,
  "dimension_averages": {
    "CONCEPTUAL_KNOWLEDGE": 78.2,
    "USE_APPLY_KNOWLEDGE": 75.7,
    "EVALUATE_CREATE_KNOWLEDGE": 70.1,
    "ETHICS_KNOWLEDGE": 65.4
  },
  "strongest_dimension": "CONCEPTUAL_KNOWLEDGE",
  "weakest_dimension": "ETHICS_KNOWLEDGE",
  "time_period": { "filter": "all_time" },
  "level_distribution": { "1": 0, "2": 3, "3": 8, "4": 10, "5": 2 }
}

Planned · v1.1

Planned endpoints

Three endpoints return 501 today and are scheduled for v1.1.

Method	Path	Purpose
POST	`/organizations/{id}/invites`	Batch invite users.
GET	`/organizations/{id}/export`	Export results.
POST	`/webhooks`	Register a webhook for assessment events.

Reference

Dimensions & weights

Four dimensions contribute to the overall score with the weights below.

Dimension	Weight	What it measures
`CONCEPTUAL_KNOWLEDGE`	30%	AI fundamentals, terminology, capabilities, limitations.
`USE_APPLY_KNOWLEDGE`	30%	Practical application, prompt engineering, workflow integration.
`EVALUATE_CREATE_KNOWLEDGE`	25%	Critical assessment of AI outputs, quality evaluation.
`ETHICS_KNOWLEDGE`	15%	Bias, privacy, transparency, accountability.

Literacy levels

The overall score maps to one of five levels, each with its own learning-path profile.

Level	Title	Range	Description
1	Baseline Awareness	0 – 20	Basic awareness, limited practical knowledge.
2	Informed User	21 – 40	Familiar with concepts, occasional tool use.
3	Capable Practitioner	41 – 60	Competent understanding, regular tool use.
4	Critical Evaluator	61 – 80	Proficient, can critically evaluate AI outputs.
5	AI Champion	81 – 100	Advanced understanding, sophisticated application.

Adaptive testing

AILAT uses a 2-Parameter Logistic (2PL) Item Response Theory model. After each answer, the system updates the proficiency estimate and selects the next question to maximize Fisher information at that level.

Adaptive tracks

Track	Proficiency	Difficulty mix
Foundational	≤ −1.0	Prioritizes EASY (70%) with some MEDIUM.
Standard	−1.0 … 1.0	Balanced mix based on IRT.
Advanced	≥ 1.0	Prioritizes DIFFICULT (70%) with some MEDIUM.

Error recovery

The API prioritizes assessment continuity. Most failure modes have an automatic fallback that keeps the session usable.

Scenario	What happens
Question bank exhausted	An LLM generates a fallback question that keeps IRT parameters valid.
LLM evaluation unavailable	Falls back to difficulty-adjusted scoring (0.4 – 0.65).
Results generation fails	Status set to `pending_results`; retry `/results` later.
Session idle > 30 min	Auto-paused; resume via `PUT /status`.
Rate limiter unavailable	Returns `503` with `Retry-After: 30`.
Network timeout on answer	Re-submit the same answer (idempotent).

Best practices

Session management

Store assessment_id securely between requests.
Sessions expire after 24h; auto-pause after 30 min idle.
Check expires_at to anticipate expiration.

Answer submission

Include response_time_ms when possible (improves IRT accuracy).
Acceptable range: 5 – 60s for MC, 60 – 300s for open-ended.
The same answer can be safely re-submitted (idempotent).

Error handling

Retry with exponential backoff for 429 and 503.
Use recovery_action for user-facing guidance.
Poll on 202 for pending results.

Result visualization

Use radar charts for dimension scores.
Color-code literacy levels 1 – 5.
Highlight strengths (≥ 70%) and growth areas (< 60%).

Code examples

Drop-in patterns for the two most common integration headaches.

Retry with exponential backoff

async function apiRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    if (response.status === 429 || response.status === 503) {
      const retryAfter = response.headers.get('Retry-After') || 5;
      await new Promise((r) =>
        setTimeout(r, retryAfter * 1000 * Math.pow(2, i))
      );
      continue;
    }
    return response;
  }
  throw new Error('Max retries exceeded');
}

Poll for pending results

async function getResults(assessmentId, token) {
  while (true) {
    const res = await fetch(
      `https://ailat.io/api/v1/assessments/${assessmentId}/results`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    if (res.status === 200) return res.json();
    if (res.status === 202) {
      const delay = res.headers.get('Retry-After') || 30;
      await new Promise((r) => setTimeout(r, delay * 1000));
      continue;
    }
    throw new Error(`Unexpected status: ${res.status}`);
  }
}

Support

Email support

mail@founderly.com

Health check

GET /api/v1/health

Changelog

v1.0.1

2026-04-16

Adaptive track thresholds adjusted from ±1.5 to ±1.0 for better responsiveness.
Adaptive track now continuously re-evaluates during the assessment.
Sessions auto-pause after 30 minutes of inactivity.
Answer submission is idempotent (safe to retry on network timeout).
Pending results return 202 instead of 500.
Unimplemented endpoints return 501 with clear messaging.
Added strongest_dimension, weakest_dimension, time_period to organization results.
Added Cache-Control headers to results and analytics endpoints.
Rate limiter fails closed (503) instead of silently bypassing.
Authentication errors unified to prevent token enumeration.

v1.0.0

2025-04-27

Initial API release.
Core assessment endpoints.
Organization analytics.
Adaptive testing with IRT 2PL model.
Learning path recommendations.

Planned for v1.1

Batch invitations (POST /organizations/{id}/invites).
Data export (GET /organizations/{id}/export).
Webhook notifications (POST /webhooks).
Enhanced organization management.

All timestamps use ISO 8601 format. All IDs use the prefix pattern (asmt_, org_, user_).