API
Quickstart
Everything below the graph endpoints is org-scoped by an API key. In this dev build, pnpm seed prints a key and demo learner ids.
# seed the local db, copy the printed key
pnpm seed
# the tutoring loop
curl -H "Authorization: Bearer $KEY" localhost:3000/api/v1/learners/$ID/session/next
curl -X POST -H "Authorization: Bearer $KEY" \
-d '{"topicId":"$TOPIC","grade":"correct","mode":"review"}' \
localhost:3000/api/v1/learners/$ID/session/answer
curl -H "Authorization: Bearer $KEY" localhost:3000/api/v1/learners/$ID/memoryEndpoints
| Method | Path | Auth | What it returns |
|---|---|---|---|
GET | /api/v1/subjects | none | Subjects with topic counts and domains |
GET | /api/v1/topics?q=&subject=&ageMin=&ageMax= | none | Search micro-topics |
GET | /api/v1/topics/:id | none | One topic, with evidence and assessment prompt |
GET | /api/v1/topics/:id/prerequisites?transitive=&strength= | none | What must come first, and why |
GET | /api/v1/topics/:id/unlocks | none | What this topic opens up |
GET | /api/v1/standards/:key/topics | none | Topics distilled from a curriculum standard |
GET | /api/v1/topics/:id/content | none | Lesson, doodle scenes, video query, quiz item bank |
GET | /api/v1/learners | key | Learners in your org |
POST | /api/v1/learners | key | Create a learner (displayName, birthYear) |
GET | /api/v1/learners/:id | key | Learner with memory summary and per-subject progress |
GET | /api/v1/learners/:id/session/next?subject= | key | What to ask now: placement probe, refresh, or new topic |
POST | /api/v1/learners/:id/session/answer | key | Record a grade; credit propagates, misses flag a prerequisite |
GET | /api/v1/learners/:id/memory | key | Per-topic memory: strength, recall probability, due date |
GET | /api/v1/learners/:id/mastery | key | Mastered and in-progress topic ids |
POST | /api/v1/learners/:id/mastery | key | Import external state (vouched, audited later) |
GET | /api/v1/learners/:id/levels | key | Per-subject level bands (two-year, grade-mapped) |
GET | /api/v1/packs | key | Custom packs you can use: own, shared in, public |
POST | /api/v1/packs | key | Create a pack (name, description) |
GET | /api/v1/packs/:id | key | A pack with topics and question pools |
PATCH | /api/v1/packs/:id | key | Set visibility: private or public |
POST | /api/v1/packs/:id/topics | key | Add a custom topic (subject, name, ages, prereqIds) |
POST | /api/v1/packs/:id/topics/:topicId/items | key | Add a question (mcq, true_false, numeric) |
POST | /api/v1/packs/:id/share | key | Share the pack with an email |
PUT | /api/v1/learners/:id/packs | key | Switch packs on for a learner (packIds) |
GET | /api/v1/learners/:id/frontier?subject=&limit= | key | Ranked list of what is within reach |
GET | /api/v1/learners/:id/path/:topicId | key | Learning path to a goal topic |
GET | /api/v1/learners/:id/assessment/next?subject= | key | Alias of session/next |
POST | /api/v1/learners/:id/assessment/:topicId | key | Alias of session/answer, outcome wording |
GET | /api/v1/learners/:id/report?curriculum= | key | Standards coverage report |
Free tier
The graph endpoints (topics, prerequisites, unlocks, standards) are also available as a stateless MCP server: pnpm --filter @atlas/mcp-server start. Point any agent at it; no account needed. The hosted API adds the per-learner memory model on top.