From a key to your first
diagnosis in five minutes.

Cognivia reads why an answer was wrong, models a learner's memory state, and returns what to do next. Send what a learner did; get diagnostics back. One base URL, one key, three calls.

Get an API key See a sample report

1 Get a key

Open the developer console and create a live key (it is shown once). For a first look with no signup, the demo key sk_demo works immediately on the stateless endpoints below. The base URL is the same for everything:

Base URL

https://cognivia-platform.vercel.app/v1

2 Try it instantly (no history)

Send one set of answers and get the full Session Report back: the Learning Genome, a per-question diagnosis, and the next review for each. This endpoint is stateless, so the demo key is enough.

POST /v1/analyze · curl

curl https://cognivia-platform.vercel.app/v1/analyze \
  -H "Authorization: Bearer sk_demo" -H "Content-Type: application/json" \
  -d '{ "attempts": [
        { "subject": "Physics", "question": "SI unit of force?",
          "answer": "joule", "correct": false, "latencyMs": 2100, "confidence": 5 }
      ] }'

# -> { "id": "CGV-API-...", "genome": {...}, "cells": [...], "rows": [...] }

3 Ingest what a learner did

To build real, longitudinal memory state, stream events as they happen. This is the "hook onto any app" write path, and it needs a live key. Send one event or a batch.

POST /v1/traces · curl

curl https://cognivia-platform.vercel.app/v1/traces \
  -H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
  -d '{ "events": [
        { "learner_ref": "alice", "concept": "Photosynthesis",
          "occurred_at": "2026-08-01T10:00:00Z",
          "observed": { "is_correct": false, "confidence": 80, "latency_ms": 4000 } }
      ] }'

# -> { "accepted": 1, "inserted": 1, "rejected": [] }

4 Read the memory state

Here is the good part. Ask for a learner's current state and you get back the whole picture per concept: how well it is holding (accuracy with a Wilson interval), when it is due (FSRS-6 stability and retrievability), and the full Learning Genome, including the forgetting rate λ from a Bayesian posterior with a credible interval. Seven variables are there from the start; three more (spacing response, speed vs accuracy, error recovery) fill in once the learner has enough spaced history, ten in all. Each concept also comes with a plain-language diagnosis: what is going on and what to do about it. Concepts you have barely seen say insufficient_evidence rather than guess.

GET /v1/learners/:id/memory-state · curl

curl https://cognivia-platform.vercel.app/v1/learners/alice/memory-state \
  -H "Authorization: Bearer sk_live_..."

# -> {
#   "learner": "alice",
#   "genome": { "lambda_weighted_mean": 0.81, "retrieval_strength": 0.77,
#               "confidence_gap": 0.08, "accuracy": 0.79 },   # whole-learner view
#   "concepts": [
#     { "concept": "Photosynthesis", "status": "ok",
#       "accuracy": 0.67, "accuracy_ci95": [0.21, 0.94],
#       "retrievability_now": 0.91, "fsrs_stability": 7.6,
#       "next_review_at": "2026-08-30",
#       "genome": {
#         "lambda": { "value": 0.74, "ci95": [0.55, 1.02],
#                     "archetype": "AVERAGE", "label": "developing" },
#         "retrieval_strength":       { "value": 0.81 },
#         "latency_index":            { "value": 0.78 },
#         "confidence_gap":           { "value": 0.0  },
#         "consolidation_efficiency": { "value": 0.74 },
#         "fatigue_susceptibility":   { "value": 0.0  },
#         "pattern_dominance": { "value": null, "dominant_error": null },
#         "n_observations": 6
#       },
#       "diagnosis": { "headline": "Held and consolidating", "priority": "low",
#                      "action": "Space this concept further out." } }
#   ],
#   "engine": "fsrs-6.0"
# }

Every genome variable ships with a basis field naming the science it rests on (trimmed above for readability). The full shape lives in the OpenAPI spec that ships with the SDK.

5 Or use an SDK

The same engine is available as a Python package, a CLI, and an MCP server for AI agents, so it drops into wherever you already work.

Python

pip install cognivia
then Cognivia(api_key).diagnose_learner("alice","Photosynthesis")

CLI

npm i -g @cognivia/cli
then cognivia diagnose --demo

MCP server

npx -y @cognivia/mcp
exposes diagnose, memory-state, and report as agent tools.

Reference

The rest, in one place.

Endpoints: POST /v1/traces, POST /v1/diagnose, GET /v1/learners/:id/memory-state (real, stateful); POST /v1/analyze, POST /v1/analyze/item (illustrative, stateless); POST/GET /v1/content/items, POST/GET /v1/content/prerequisites (your content maps); GET /v1/health.
Auth: Send your key as Authorization: Bearer <key>. Demo keys (sk_demo…) work on the stateless endpoints; a live key (sk_live_…) is what reads stored learner data.
The attempt shape: One answered item: { subject, question, answer, correct, latencyMs, confidence }. Confidence is 1–5 (0–100 or 0–1 also accepted). REST aliases: outcome, latency_ms, concept, response.
The Learning Genome: Each concept in memory-state carries seven core variables: lambda (forgetting rate, Bayesian posterior with a credible interval), retrieval_strength, latency_index, confidence_gap, consolidation_efficiency, fatigue_susceptibility, and pattern_dominance. Three longitudinal variables, spacing_response, speed_accuracy, and error_recovery, are null until there is enough spaced history, then fill in (ten total). Each concept also carries a diagnosis (headline, signal, action, priority), and there is a learner-level genome at the top of the response.
Sharper diagnosis on your content: Optional, and it makes /v1/diagnose smarter on your own items. Upload an item map so a wrong answer names the misconception behind it: POST /v1/content/items with { items: [{ item_ref, distractors: { "the wrong option": "the misconception it reveals" } }] }. Upload a prerequisite map so a miss can be traced to a weak foundation: POST /v1/content/prerequisites with { prerequisites: [{ concept: "Adding fractions", requires: ["Equivalent fractions"] }] }. Both are scoped to your account and use your own item_ref and concept strings, no shared taxonomy. GET either to read back what you have stored.
Uncertainty: Every inferred field carries its basis. Stored metrics come with a sample size and interval; low-n concepts return insufficient_evidence rather than a bare number.
Rate limits: 120 req/min on diagnose and memory-state, 60/min on reports. A 429 means slow down; the response says for how long.
Full spec: OpenAPI 3.0 (docs/openapi-v1.yaml) · the Intelligence page

Get an API key Talk to us