Give it a document. Ask it questions. It answers from what it learned.

The path through it

Six calls, in this order, once. After that you are just asking questions.

1. Get a key

   POST/v1/keys while signed in as a person. The secret is shown once and never again; only a hash of it is stored. A machine key cannot mint another key, so an agent has to be handed one.

2. Create a learner

   POST/v1/learners with a name. Keep the learner_id that comes back, because almost every later call takes it.

3. Open a session, then activate it

   POST/v1/sessions with the learner id, then POST/v1/sessions/{id}/activate with no body. Activating asks for compute before you need it. Compute scales to zero, so without this step your first request against a cold learner carries the whole start-up wait and can time out. Activating turns that wait into a stage you can show someone.

4. Add a source: quote first, then confirm

   POST/v1/sources with a file, a URL or a repository. Sent without confirm it trains nothing and returns an estimate: how much material it found, roughly what it will cost, and roughly how long. Send the same call again with confirm set and it starts.

5. Watch the job

   GET/v1/jobs/{id} for the state, or GET/v1/jobs/{id}/events for a live stream of it. When it finishes, the report tells you how much the learner gained on the material you gave it.

6. Ask it something

   POST/v1/chat/completions, shaped like the chat call most clients already speak. Under load it answers with a job to poll instead of an answer, and with streaming turned on you get events as the text arrives.

One example, start to finish

Teach a page and ask about it. Two calls to teach, because nothing trains until you confirm, and one to ask.

# 1 · create a learner
curl https://api.learnerlabs.ai/v1/learners \
  -H "Authorization: Bearer $LEARNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "product docs"}'

# 2 · quote the source. Nothing trains, nothing is charged
curl https://api.learnerlabs.ai/v1/sources \
  -H "Authorization: Bearer $LEARNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"learner_id": "YOUR_LEARNER_ID", "kind": "url",
       "url": "https://example.com/docs/changelog"}'

# → { "confirmed": false, "quote": { "tokens": 21504, "est_usd": 0.31,
#     "est_seconds": 180 } }   send it again with "confirm": true to start

# 3 · ask it, once the job has finished
curl https://api.learnerlabs.ai/v1/chat/completions \
  -H "Authorization: Bearer $LEARNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "learner-1.0:YOUR_LEARNER_ID",
       "messages": [{"role": "user", "content": "What changed in v4?"}],
       "max_tokens": 256, "temperature": 0}'

For agentsComing soon

A hosted tool endpoint so an agent can teach a document, ask a learner and replay any of the published demonstrations without you writing a client.

# coming soon
claude mcp add --transport http learner https://mcp.learnerlabs.ai/mcp \
  --header "Authorization: Bearer sk-your-key"

Until it is live, the same tools install from a local configuration block. The demonstrations page carries the version that works today.

Endpoint reference

Keys

Learners

Sessions

Teaching

Asking

Conversations

Restore points

Billing and records