API Reference

BrainGap API

Build adaptive assessments with psychometric precision. Two endpoints for the core loop, dozens more when you need them.

Base URL 
https://api.braingap.io/v1
<50ms
Latency
REST
JSON API

Authentication

All requests require two headers:

Required Headers
Authorization: Bearer sk_live_xxxxx
X-User-Id: your_user_identifier
Keep your API key secure
Never expose it in client-side code. Make API calls from your backend.

Quickstart

The complete assessment loop in two API calls.

1. Get the optimal next question 
curl -X POST https://api.braingap.io/v1/assess/next \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-User-Id: user_123" \
  -H "Content-Type: application/json" \
  -d '{"blueprint": "aws-solutions-architect"}'
2. Submit the user's answer 
curl -X POST https://api.braingap.io/v1/assess/respond \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-User-Id: user_123" \
  -H "Content-Type: application/json" \
  -d '{"interactionId": "uuid", "response": "B"}'

Item Formats

BrainGap supports multiple question formats. Some are scored instantly (deterministic), others use AI scoring for open-ended responses.

Instant scoring
multiple_choice
Select one option from A-D. Returns options[] array.
true_false
Evaluate a statement. Response is "true" or "false".
matching
Match terms to definitions. Returns pairs[] with left/right sides.
ordering
Arrange items in correct sequence. Returns options[] to reorder.
AI scoring
short_answer
Open-ended text response. Scored against rubric key points.
teach_back
Explain a concept in your own words. Tests deep understanding.

Response format by type

Examples
// multiple_choice: option letter or index
{ "response": "B" }

// true_false
{ "response": "false" }

// matching: comma-separated pair indices (left-right)
{ "response": "0-2,1-0,2-1" }

// ordering: comma-separated sequence
{ "response": "2,0,3,1" }

// short_answer / teach_back: free text
{ "response": "VPCs provide network isolation..." }
Restricting formats
Use itemFormats: ["multiple_choice", "true_false"] in /assess/next to get only instant-scoring formats.
POST /v1/assess/next

Get the optimal next question using Maximum Fisher Information selection.

Request Body

blueprint string Required. Blueprint ID or slug.
focusTopic string Optional. Restrict to a specific topic.
focusConcepts array Optional. Array of concept IDs to focus on.

Response

200 OK
{
  "interaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "conceptName": "VPC Subnet Design",
    "type": "multiple_choice",
    "prompt": "A company needs to design...",
    "options": ["A) ...", "B) ..."]
  },
  "meta": {
    "readinessScore": 0.72,
    "conceptsMastered": 46,
    "suggestedStopReason": null
  }
}
POST /v1/assess/respond

Submit the user's answer. Returns score immediately for deterministic types, or pending for LLM-scored.

Request Body

interactionId string Required. From /next response.
response string Required. The user's answer.
responseTimeMs integer Optional. Time spent in milliseconds.

Response

200 OK
{
  "resultId": "650e8400-e29b-41d4-a716-446655440001",
  "score": 1.0,
  "scoring": "complete",
  "explanation": "Correct! Creating subnets...",
  "masterySnapshot": {
    "previousScore": 0.62,
    "newScore": 0.67
  }
}
POST /v1/assess/skip

Skip the current question and get a new one. Returns the same shape as /next.

Request Body

interactionId string Required. ID of interaction being skipped.
blueprint string Required. Same as /next.
reason string Optional. "too_hard", "unclear", "already_know".
Example Request 
curl -X POST https://api.braingap.io/v1/assess/skip \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-User-Id: user_123" \
  -H "Content-Type: application/json" \
  -d '{"interactionId": "550e8400-...", "blueprint": "aws-solutions-architect", "reason": "unclear"}'

Response

200 OK (same shape as /next)
{
  "interaction": {
    "id": "660e8400-e29b-41d4-a716-446655440002",
    "conceptName": "IAM Role Policies",
    "type": "multiple_choice",
    "prompt": "Which IAM policy type...",
    "options": ["A) ...", "B) ..."]
  },
  "meta": {...}
}
POST /v1/assess/feedback

Submit thumbs up/down feedback on a scored interaction. Used to improve question quality.

Request Body

resultId string Required. From /respond response.
rating string Required. "up" or "down".
comment string Optional. User's comment.
Example Request 
curl -X POST https://api.braingap.io/v1/assess/feedback \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-User-Id: user_123" \
  -H "Content-Type: application/json" \
  -d '{"resultId": "650e8400-...", "rating": "down", "comment": "Answer was ambiguous"}'

Response

200 OK
{
  "acknowledged": true
}

Attempts

Group interactions into formal assessment sessions with defined start/end.

POST /v1/attempts

Create a new assessment attempt. All subsequent /next and /respond calls are associated with this attempt.

Request 
curl -X POST https://api.braingap.io/v1/attempts \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-User-Id: user_123" \
  -H "Content-Type: application/json" \
  -d '{"blueprint": "aws-solutions-architect", "maxItems": 20, "timeLimitMinutes": 30}'
Response
{
  "attemptId": "att_abc123",
  "status": "in_progress",
  "blueprint": "aws-solutions-architect",
  "startedAt": "2024-01-15T10:30:00Z",
  "maxItems": 20,
  "timeLimitMinutes": 30
}
GET /v1/attempts/{id}

Get attempt details including progress and results.

Response
{
  "attemptId": "att_abc123",
  "status": "completed",
  "itemsCompleted": 20,
  "score": 0.78,
  "theta": 0.92,
  "standardError": 0.31,
  "startedAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:52:00Z"
}
GET /v1/attempts List all attempts for user
POST /v1/attempts/{id}/close Close attempt early (abandoned/timeout)
GET /v1/users/{userId}/gaps

Priority-ranked gap analysis comparing mastery to blueprint requirements.

Response
{
  "summary": {
    "overallReadiness": 0.72,
    "conceptsMastered": 46,
    "conceptsWithGaps": 22
  },
  "gaps": [
    {
      "conceptName": "VPC Subnet Design",
      "gapSize": 0.45,
      "importance": "required"
    }
  ]
}
GET /v1/users/{userId}/mastery

Full mastery profile with IRT ability estimates per concept. Use this for raw measurement data.

Request 
curl https://api.braingap.io/v1/users/user_123/mastery?blueprint=aws-solutions-architect \
  -H "Authorization: Bearer $API_KEY"
Response
{
  "overallProficiency": 0.72,
  "precision": "high",
  "interactionCount": 45,
  "concepts": [
    {
      "conceptId": "vpc-subnet-design",
      "conceptName": "VPC Subnet Design",
      "theta": 0.85,
      "standardError": 0.32,
      "proficiencyScore": 0.80,
      "state": "progressing"
    }
  ]
}
Mastery vs Gap Analysis
Use mastery for raw IRT measurements (theta, SE). Use gaps for actionable study recommendations with priority ranking.
GET /v1/users/{userId}/progress Progress summary over time
DELETE /v1/users/{userId} Delete user data (GDPR compliance)

Blueprints

Knowledge definitions that assessments run against. Each blueprint contains topics and concepts.

POST /v1/blueprints

Create a new blueprint. Choose a decomposition mode based on your needs.

Decomposition Modes

ai Recommended

Provide a description or source material and let AI decompose it into topics and concepts. Fast setup for certifications, courses, and general knowledge domains.

manual

Define every topic and concept yourself. Full control for academic research, psychometric validation, or when you have existing curriculum structures.

AI Decomposition 
curl -X POST https://api.braingap.io/v1/blueprints \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS Solutions Architect Associate",
    "slug": "aws-saa",
    "mode": "ai",
    "source": {
      "type": "description",
      "content": "AWS SAA-C03 certification covering compute, storage, networking, databases, security, and cost optimization on AWS."
    }
  }'
Manual Definition 
curl -X POST https://api.braingap.io/v1/blueprints \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cognitive Psychology 101",
    "slug": "psych-101",
    "mode": "manual",
    "topics": [
      {
        "name": "Memory Systems",
        "concepts": [
          { "name": "Working Memory", "description": "..." },
          { "name": "Long-term Potentiation", "description": "..." }
        ]
      }
    ]
  }'
Response
{
  "slug": "aws-saa",
  "status": "decomposing",
  "estimatedCompletion": "2024-01-15T10:35:00Z",
  "webhookOnComplete": true
}
AI source types
description - text description of the domain
url - link to syllabus, exam guide, or course outline
document - uploaded PDF or text file (base64)
When to use manual mode
Use manual mode when you need psychometric defensibility, have existing validated item banks, or require exact alignment with curriculum standards. Manual blueprints give you full control over concept granularity and prerequisite relationships.

List & Get Blueprints

GET /v1/blueprints

List all blueprints available to your account.

Response
{
  "blueprints": [
    {
      "slug": "aws-solutions-architect",
      "name": "AWS Solutions Architect Associate",
      "topicCount": 12,
      "conceptCount": 68,
      "visibility": "public"
    },
    {
      "slug": "logical-fallacies",
      "name": "Logical Fallacies",
      "topicCount": 6,
      "conceptCount": 24,
      "visibility": "public"
    }
  ]
}
GET /v1/blueprints/{slug}

Get blueprint details including topic/concept structure.

Response
{
  "slug": "aws-solutions-architect",
  "name": "AWS Solutions Architect Associate",
  "description": "AWS SAA-C03 exam preparation",
  "topics": [
    {
      "name": "Networking",
      "concepts": ["VPC Subnet Design", "Route Tables", "..."]
    }
  ]
}

Manage Concepts

Add, update, or remove concepts from a blueprint. Useful for refining AI-generated structures or maintaining manual blueprints.

POST /v1/blueprints/{slug}/concepts Add concepts to a topic
PATCH /v1/blueprints/{slug}/concepts/{id} Update concept details
DELETE /v1/blueprints/{slug}/concepts/{id} Remove a concept
Add concept 
curl -X POST https://api.braingap.io/v1/blueprints/aws-saa/concepts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topicId": "networking",
    "name": "Transit Gateway",
    "description": "Centralized hub for connecting VPCs and on-premises networks",
    "prerequisites": ["vpc-basics", "route-tables"]
  }'
Prerequisite chains
Define prerequisites to create learning paths. BrainGap will assess prerequisite concepts first and use warm-start propagation to seed ability estimates for dependent concepts.

Cohorts

Analyze groups of users together. Identify common gaps, track team progress, detect item bias.

POST /v1/cohorts/gaps

Find common knowledge gaps across a group of users.

Request 
curl -X POST https://api.braingap.io/v1/cohorts/gaps \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userIds": ["user_1", "user_2", "user_3"], "blueprint": "aws-solutions-architect"}'
Response
{
  "cohortSize": 3,
  "commonGaps": [
    {
      "conceptName": "VPC Peering",
      "affectedUsers": 3,
      "avgGapSize": 0.52
    },
    {
      "conceptName": "IAM Policies",
      "affectedUsers": 2,
      "avgGapSize": 0.38
    }
  ]
}
POST /v1/cohorts/progress Aggregate progress tracking
POST /v1/cohorts/dif Differential Item Functioning analysis
POST /v1/cohorts/compare Compare two cohorts head-to-head

Management

Create and manage proprietary blueprints, concepts, and interactions. Enterprise only.

POST /v1/manage/blueprints

Create a new blueprint. AI automatically decomposes it into topics and concepts.

Request 
curl -X POST https://api.braingap.io/v1/manage/blueprints \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Onboarding",
    "description": "Internal policies and procedures",
    "sourceUrl": "https://wiki.company.com/onboarding",
    "visibility": "private"
  }'
Response
{
  "slug": "company-onboarding",
  "status": "decomposing",
  "message": "Blueprint queued for decomposition"
}

Blueprint Management

GET /v1/manage/blueprints/{slug} Get with full concept tree
POST /v1/manage/blueprints/{slug}/refresh Regenerate all interactions

Concept Operations

POST /v1/manage/concepts/{id}/split Split into multiple concepts
POST /v1/manage/concepts/merge Merge duplicate concepts

Interaction Management

GET /v1/manage/concepts/{id}/interactions List all items for concept
POST /v1/manage/concepts/{id}/interactions Create custom interaction
PATCH /v1/manage/interactions/{id} Update interaction content
DELETE /v1/manage/interactions/{id} Remove interaction

Webhooks

Get notified when async events complete. All payloads include HMAC signature for verification.

POST /v1/webhooks
Register Webhook 
curl -X POST https://api.braingap.io/v1/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-app.com/webhooks", "events": ["scoring.complete"]}'
Response
{
  "webhookId": "wh_abc123",
  "secret": "whsec_xxxxxxxx",
  "events": ["scoring.complete"]
}

Example Payload

POST to your endpoint
{
  "event": "scoring.complete",
  "timestamp": "2024-01-15T10:32:00Z",
  "data": {
    "resultId": "650e8400-...",
    "userId": "user_123",
    "score": 0.85,
    "explanation": "Strong understanding of..."
  }
}

Available Events

scoring.complete LLM scoring finished for short answer/teach-back
attempt.completed Assessment attempt finished
blueprint.ready Blueprint decomposition complete
GET /v1/webhooks List registered webhooks
DELETE /v1/webhooks/{id} Remove webhook

Errors

All errors follow a consistent format.

Error Response
{
  "error": {
    "code": "blueprint_not_found",
    "message": "Blueprint 'xyz' not found"
  }
}
400 Bad request - malformed input
401 Missing or invalid API key
403 Insufficient permissions
404 Resource not found
429 Rate limited
500 Server error

AI Detection

Coming Soon

Detect when users are using AI assistants to answer questions instead of demonstrating genuine knowledge.

Why this matters

Assessments only work when responses reflect actual knowledge. If users copy questions into ChatGPT, your mastery data becomes meaningless. AI detection flags suspicious patterns so you can trust your results.

How it works

We analyze multiple behavioral and linguistic signals across each assessment session:

Response timing

AI-assisted answers show distinctive timing patterns. Too fast for the complexity, or suspiciously consistent delays that suggest copy-paste workflows.

Linguistic fingerprints

LLM outputs have telltale patterns: hedging phrases, certain structural quirks, vocabulary choices that differ from natural human responses.

Consistency analysis

Real knowledge shows natural variation. AI-assisted users often show impossible consistency, or wild swings between expert and novice responses.

Session behavior

Tab switching patterns, focus events, paste detection, and other browser signals that indicate external tool usage.

Planned API

AI detection scores will be included in assessment results:

Response (planned)
{
  "resultId": "650e8400-...",
  "score": 0.85,
  "aiDetection": {
    "confidence": 0.12,
    "flag": "unlikely",
    "signals": []
  }
}
When AI is detected
{
  "resultId": "650e8400-...",
  "score": 0.95,
  "aiDetection": {
    "confidence": 0.87,
    "flag": "likely",
    "signals": [
      "response_timing_anomaly",
      "linguistic_pattern_match",
      "paste_event_detected"
    ]
  }
}
Interested in early access? We're looking for beta partners to help refine detection accuracy. Get in touch.

Questions? hello@braingap.io