Docs

How streams and pulls work, a first call you can paste into a terminal, and every endpoint. To see a few days of calls step by step, read the example.

A practice plan and its saved sets

A practice app such as 6problems needs new questions over time, plus a way to reopen yesterday’s set or recover it after a dropped connection. Two API objects handle that:

Stream = what to practise

A description written in a conversation at /chat/completions, in the OpenAI Chat Completions shape: you say what the learner should practise, an assistant asks what it needs to know, then writes the stream’s definition, and the service writes the code that makes its questions and works out their answers. Or, with no model, a named list of skills and limits sent to /streams/create. Your app decides when to change the stream. Each change creates a revision.

Pull = one saved set

Questions saved under a key your app chooses, such as a date or session ID. Retry with the same stream, key and count to recover that set, even after the stream changes.

The developer state viewer shows streams, revisions and pulls after your API calls. Your app presents the questions and keeps track of the learner’s progress.

Make your first pull

API key required. Every call carries one of your API keys. The examples write it as YOUR_API_KEY: replace that with your key before you run them. Make a key with the button below; API keys, after the example, says more.

Paste this example into a terminal with curl. It describes a stream in one message to /chat/completions, requests a set, then retries the same request. The first response comes back once the stream is saved. The service then writes and checks the code that makes the stream’s questions, which takes about half a minute, and the first pull waits for it: until the code is written it answers 503 with Retry-After, and curl’s --retry sends it again, writing each answer over answer.json and printing the last. The pulls after it take well under a second. The first response’s stream names the stream the assistant saved; when it is null the assistant asked a question instead, so add its reply and your answer to messages and send them again. The last two responses contain the same questions; the retry has replayed: true. This example uses the pull’s JSON key for retries.

# Put one of your API keys in place of YOUR_API_KEY. Make one at https://accounts.problemsapi.com/user

# Make a stream for Maya by saying what she should practise. The assistant writes the stream's definition, and the turn answers once it is saved: the answer's stream names the saved stream. Then the service has a model write the code that makes the stream's questions and works out their answers, and a second call to the model solve some of them blind. That takes about half a minute; until it is done the stream's pulls answer 503 try_again, and the revision's program on /streams/get says when it is.
curl -X POST 'https://api.problemsapi.com/chat/completions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"model":"stream:maya","messages":[{"role":"user","content":"Maya is in grade 4. Make her a stream of fractions, half of each kind: mixed numbers to write as improper fractions, with whole parts up to 9 and denominators 2, 3, 4, 5 and 8; and fractions to simplify, with denominators up to 12."}]}'

# Pull today's six questions. The key is the date. The stream's code makes the questions and works out each answer, with no call to a model, and each comes with its LaTeX so a sheet can typeset it. While the code is still being written the pull answers 503 with Retry-After and saves nothing, so an app sends it again after that wait.
curl -X POST 'https://api.problemsapi.com/pulls/create' \
  -sS --retry 30 -o answer.json \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"stream":"maya","key":"2026-09-29","count":6}' \
  && cat answer.json

# The app retries the same pull after a dropped connection. It gets the same six questions back, marked as a replay, and nothing is made or saved again.
curl -X POST 'https://api.problemsapi.com/pulls/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"stream":"maya","key":"2026-09-29","count":6}'

A model writes the assistant’s replies and the code that makes the questions, so yours will differ from the recorded example. Use the same caller identity in the state viewer to inspect your calls.

Example pull response, recorded from the program
{
  "pull": {
    "stream": "maya",
    "key": "2026-09-29",
    "revision": 1,
    "requested": 6,
    "questions": [
      {
        "type": "number",
        "id": "1-0",
        "prompt": "Simplify 4/8.",
        "problem": null,
        "latex": "\\text{Simplify } \\frac{4}{8}",
        "answer": {
          "numerator": 1,
          "denominator": 2
        },
        "answer_text": "1/2",
        "form": "simplest_fraction",
        "similarity": "written/simplifying"
      },
      {
        "type": "number",
        "id": "1-1",
        "prompt": "Write 4 5/8 as an improper fraction.",
        "problem": null,
        "latex": "4\\tfrac{5}{8}",
        "answer": {
          "numerator": 37,
          "denominator": 8
        },
        "answer_text": "37/8",
        "form": "improper_fraction",
        "similarity": "written/improper fractions"
      },
      {
        "type": "number",
        "id": "1-3",
        "prompt": "Simplify 3/12.",
        "problem": null,
        "latex": "\\text{Simplify } \\frac{3}{12}",
        "answer": {
          "numerator": 1,
          "denominator": 4
        },
        "answer_text": "1/4",
        "form": "simplest_fraction",
        "similarity": "written/simplifying"
      },
      {
        "type": "number",
        "id": "1-7",
        "prompt": "Write 8 3/4 as an improper fraction.",
        "problem": null,
        "latex": "8\\tfrac{3}{4}",
        "answer": {
          "numerator": 35,
          "denominator": 4
        },
        "answer_text": "35/4",
        "form": "improper_fraction",
        "similarity": "written/improper fractions"
      },
      {
        "type": "number",
        "id": "1-10",
        "prompt": "Simplify 3/6.",
        "problem": null,
        "latex": "\\text{Simplify } \\frac{3}{6}",
        "answer": {
          "numerator": 1,
          "denominator": 2
        },
        "answer_text": "1/2",
        "form": "simplest_fraction",
        "similarity": "written/simplifying"
      },
      {
        "type": "number",
        "id": "1-11",
        "prompt": "Write 7 3/4 as an improper fraction.",
        "problem": null,
        "latex": "7\\tfrac{3}{4}",
        "answer": {
          "numerator": 31,
          "denominator": 4
        },
        "answer_text": "31/4",
        "form": "improper_fraction",
        "similarity": "written/improper fractions"
      }
    ],
    "created_millis": 1794951430235,
    "token": "sFbQS4UWATOHyv4-iNDMHsFBH5Kxn4kX"
  },
  "replayed": false
}

API keys

Every call carries one of your API keys in its Authorization header, as Authorization: Bearer and then the key. The examples on these pages write YOUR_API_KEY where the key goes, so put your own key there before you run one. A pull's key field is something else: the name your app gives a saved set, such as a date.

Making a key

  1. Sign in at accounts.problemsapi.com.
  2. Open API Keys and add a key.
  3. Copy it into your server's configuration, or into the example in place of YOUR_API_KEY.

A key acts for the account that owns it: all of an account's keys reach the same streams and pulls, and no other account's. Anyone who has the key can make streams and pulls as you, so keep it on your server and out of pages your learners load. You can revoke a key on the same account page.

Keys in a learner's browser

A page your learners load takes a publishable key instead, made with POST /publishable_keys/create and your API key. It reaches only the endpoints marked “takes a publishable key”, which show questions and mark answers but never give an answer, and each account may call them only so often.

Agents

An agent can send your key the same way. A connector that signs in, such as a custom connector in claude.ai, needs no key at all: see Connect your agent.

When the API refuses your key

A refused key answers with a body whose auth_reason says which check refused it, and whose message says the same in a sentence.

Statusauth_reasonWhat it meansWhat to do
401missing_bearerThe call has no Authorization header.Add -H 'Authorization: Bearer YOUR_API_KEY' with your key in place of YOUR_API_KEY.
401invalid_api_keyThe API does not know the key. Most often YOUR_API_KEY is still in the command, or only part of the key was copied.Paste your whole key in place of the placeholder, or make a new key.
401sign_in_endedAn MCP client that signed in (a connector, not a key) sent a sign-in the API no longer knows: it ended or was revoked.Reconnect the connector and sign in again.
401revoked_api_keyThe key was revoked on the account page.Make a new key.
401expired_api_keyThe key had an expiry date, and it has passed.Make a new key.
403publishable_key_not_allowedA publishable key called an endpoint that takes only an API key.Make this call from your server with your API key.
503api_key_check_unavailableThe API could not check the key just now. Nothing was done.Send the same call again after the seconds in its Retry-After header.

Connect your agent

An agent can call this API itself over MCP, the Model Context Protocol. The API answers MCP at /mcp over Streamable HTTP: every endpoint below is a tool named after its path (/streams/create is streams_create), taking the same fields and giving back the same answer, so an agent can define a stream in conversation, pull a day's questions and check answers. The agent's MCP client sends one of your API keys as Authorization: Bearer, exactly as curl does, and acts for the account that owns it. A connector that signs in instead, such as a custom connector in claude.ai, needs only the address: it is sent to sign in with your problemsapi account and then acts for you. A refused call comes back as an error result with the same message, status and code. A publishable key sees only the endpoints marked for it.

# Claude Code
claude mcp add --transport http problemsapi 'https://api.problemsapi.com/mcp' --header 'Authorization: Bearer YOUR_API_KEY'

# A connector that signs in (claude.ai: Settings > Connectors > Add custom connector)
https://api.problemsapi.com/mcp

# Other MCP clients (mcpServers JSON)
{
  "mcpServers": {
    "problemsapi": {
      "type": "http",
      "url": "https://api.problemsapi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Put your API key in place of YOUR_API_KEY. How to get a key

What your app can rely on

Endpoints

There are 17 endpoints today. Each is a POST to https://api.problemsapi.com; requests with inputs use a JSON body. The route list and shapes come from the compiled program. Start with the quickstart and access setup.

The body is a JSON object with named fields, and so is every answer. A choice with fields, such as a skill, is an object whose type names the choice; a choice with no fields, such as an answer form, is just its name. An optional value is the value or null. A request the API does not answer with its value comes back with an HTTP status and a body of message, status and code: 400 when the request is malformed or out of bounds, 401 when it carries no API key or one Clerk does not know, has revoked or has let expire, 403 when a publishable key calls a route other than /learner/pull, /learner/check and /learner/check_photo, 404 when the stream, pull, token or ref it names does not exist, 422 when the request is valid but the data refuses it (a slug already taken, a key already pulled with another count, more answers than the pull has questions, a ref asked of a stream that runs no program), 429 when a call goes past a rate limit (its message names the limit, and Retry-After says when to send it again), and 503 when the service, or the model that answers a conversation, writes a pull's problems or words or reads a worksheet photo, could not settle it just now. A 503 carries a Retry-After header, and sending the same request again is safe.

The API describes itself in OpenAPI 3.1 at https://api.problemsapi.com/openapi.json, built from the same types as this list, so you can generate a client library for your language from it.

POST /streams/list read only

Lists your streams with each one's current revision.

Request and answers

Body

no body

Answers

  • 200 { streams: [{ slug: string, title: string, revision: int }] }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /streams/get read only

Shows one stream: its definition now (its skills, or the prompt a conversation at /chat/completions wrote), every revision so far, oldest first, the current one last, each saying what it runs: a program, its skills, or no program and why the writer gave none; and what names the program the current one runs.

Request and answers

Body

{ stream: string }

Answers

  • 200 { stream: { slug: string, title: string, revision: int }, skills: [one of { type: "mixed_to_improper", max_whole: int, denominators: [int] } { type: "add_whole", digits: int, regroup: boolean } { type: "subtract_whole", digits: int, regroup: boolean } { type: "simplify_fraction", max_denominator: int } { type: "to_decimal", max_whole: int, denominators: [int] }], prompt: string | null, revisions: [{ number: int, skills: [one of { type: "mixed_to_improper", max_whole: int, denominators: [int] } { type: "add_whole", digits: int, regroup: boolean } { type: "subtract_whole", digits: int, regroup: boolean } { type: "simplify_fraction", max_denominator: int } { type: "to_decimal", max_whole: int, denominators: [int] }], prompt: string | null, seed: int, created_millis: int, program: one of { type: "runs", program_hash: string } { type: "not_written", sent_back: [{ problems: [string] }], failed: { step: "writer_call" | "compiling" | "words_call" | "solver_call", reason: string } | null } { type: "by_skills" } { type: "writing" } { type: "replaced" } | null }], program_hash: string | null }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /streams/writing read only

Shows how the program of a revision of one of your streams was written, when a conversation defined it: each round's draft, oldest first, with the program the writer wrote (null when its call gave none) and how the draft ended: `accepted` (the revision runs it, `program_hash` names it), `returned` (sent back to the writer with these problems, which its next round fixes), or `stopped` (a step could give no answer, as `failed` says, and the next round shows the writer its draft again with why); and whether writing has ended (`ended`). The writer fixes one program over at most six rounds. While writing goes on, a round is under way, the revision's `program` on /streams/get is `writing`, and its pulls answer 503; a pull of a revision whose writer stopped starts another round.

Request and answers

Body

{ stream: string, revision: int }

Answers

  • 200 { stream: string, revision: int, drafts: [{ source: string | null, ended: one of { type: "accepted", program_hash: string, review: one of { type: "reviewed", gaps: [string] } { type: "unreviewed", reason: string } | null } { type: "returned", problems: [string] } { type: "stopped", failed: { step: "writer_call" | "compiling" | "words_call" | "solver_call", reason: string } } }], ended: boolean }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /streams/share changes data

Shares one of your streams defined by conversation under a ref: any account that sends the ref to /streams/from_ref gets a stream with the same title and prompt, running the same program, with no model call. The ref copies the stream's current revision. Sharing it again gives the same ref; once the stream is revised, sharing it gives a new ref, and the old one still copies the revision it was made for. A ref cannot be withdrawn, and whoever copies it reads the stream's title and prompt.

Request and answers

Body

{ stream: string }

Answers

  • 200 { ref: string, stream: { slug: string, title: string, revision: int }, program_hash: string }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /streams/from_ref changes data

Copies the stream shared under a ref as your stream `stream`, so an app you deploy can pin the stream it was designed with: the ref names one definition and one program, and copying it calls no model. A new slug makes a new stream; a stream already named `stream` gets the shared definition and program as its next revision, unless it already has them, in which case nothing changes. The copy draws its own sequence of questions from the program, as any new revision does, so its pulls are not the shared stream's pulls.

Request and answers

Body

{ ref: string, stream: string }

Answers

  • 200 { slug: string, title: string, revision: int }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /streams/create changes data

Makes a stream from a slug, a title and a list of skills. Sending the same stream again returns it unchanged; a slug already used by a different stream is refused.

Request and answers

Body

{
  slug: string,
  title: string,
  skills: [one of
    { type: "mixed_to_improper", max_whole: int, denominators: [int] }
    { type: "add_whole", digits: int, regroup: boolean }
    { type: "subtract_whole", digits: int, regroup: boolean }
    { type: "simplify_fraction", max_denominator: int }
    { type: "to_decimal", max_whole: int, denominators: [int] }]
}

Answers

  • 200 { slug: string, title: string, revision: int }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /streams/revise changes data

Changes a stream's skills. A change of skills makes a new revision, and pulls made before it keep their questions; the same skills again change nothing.

Request and answers

Body

{
  stream: string,
  skills: [one of
    { type: "mixed_to_improper", max_whole: int, denominators: [int] }
    { type: "add_whole", digits: int, regroup: boolean }
    { type: "subtract_whole", digits: int, regroup: boolean }
    { type: "simplify_fraction", max_denominator: int }
    { type: "to_decimal", max_whole: int, denominators: [int] }]
}

Answers

  • 200 { slug: string, title: string, revision: int }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /pulls/create changes data

Takes the next questions from a stream under a key you choose, such as the day. The same key always returns the same questions and changes nothing; the same key with a different count is refused. Each question has a `type`, an id, a prompt and its answer. A `number` question's answer is a number, and it has its LaTeX; a `text` question's answer is text, such as a command, and only a stream's program states one. A question a skill makes also has its problem as a typed tree (the numbers, the operation, and whether to set it inline or stacked in columns), from which the rest is computed. A stream defined by conversation makes its questions from the code the service wrote for its definition, which draws each question's numbers and works out its answer, and takes the names and other words it dresses a question in from lists of its own when it can, so a pull takes well under a second. When the definition needs words no list in the code can give, the code may instead ask a model for a few words, of a fixed kind such as a first name or a kind of food, and each new pull then waits a few seconds for that call, which writes the words for every question the pull would choose (two calls when its questions ask twice), except those it serves again (below). Words are used only when they hold a letter and nothing but the letters A to Z and À to ž (such as é, ß and ł), spaces, hyphens, apostrophes, periods and commas; the pull passes by a question whose words cannot be used. Words are written for the questions that ask among twice as many as the pull asks for, so a few unusable words cost nothing; past that, it can serve fewer than asked for. When no code was accepted for a definition, a model writes each pull's problems to it instead: a problem no tree poses, the model states in words with its answer, and a second call to the model solves it without seeing that answer; it is served only when the two agree. A new key may serve again as many questions as half the count it asks for, from earlier pulls of the stream's current revision, when a model call paid for them (it wrote them, or their words), so fewer are written; none whose prompt is among the last 60 the stream served. Such a question keeps its id and answer, and /pulls/why names the pull that first served it. When no question can be served, a call to the model fails, or the stream changes while they are made (it is redefined, or another of its pulls is taken), the pull answers 503 and nothing is saved, and sending it again tries again. A stream whose program cannot make a pull's questions answers 503 on each try of that pull; a conversation that changes the definition writes a new program.

Request and answers

Body

{ stream: string, key: string, count: int }

Answers

  • 200 { pull: { stream: string, key: string, revision: int, requested: int, questions: [one of { type: "number", id: string, prompt: string, problem: one of { type: "evaluate", operator: "add" | "subtract" | "multiply", operands: [one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int }], layout: "inline" | "stacked" } { type: "convert", numeral: one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int }, form: "improper_fraction" | "whole_number" | "simplest_fraction" | "decimal_number" } { type: "simplify", numeral: one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int } } | null, latex: string | null, answer: { numerator: int, denominator: int }, answer_text: string, form: "improper_fraction" | "whole_number" | "simplest_fraction" | "decimal_number", similarity: string } { type: "text", id: string, prompt: string, answer: string, similarity: string }], created_millis: int, token: string | null }, replayed: boolean }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /pulls/history read only

Lists the pulls taken from a stream, newest first.

Request and answers

Body

{ stream: string }

Answers

  • 200 { stream: string, pulls: [{ key: string, revision: int, requested: int, served: int, created_millis: int }] }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /pulls/get read only

Returns the questions of one earlier pull by its key.

Request and answers

Body

{ stream: string, key: string }

Answers

  • 200 { stream: string, key: string, revision: int, requested: int, questions: [one of { type: "number", id: string, prompt: string, problem: one of { type: "evaluate", operator: "add" | "subtract" | "multiply", operands: [one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int }], layout: "inline" | "stacked" } { type: "convert", numeral: one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int }, form: "improper_fraction" | "whole_number" | "simplest_fraction" | "decimal_number" } { type: "simplify", numeral: one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int } } | null, latex: string | null, answer: { numerator: int, denominator: int }, answer_text: string, form: "improper_fraction" | "whole_number" | "simplest_fraction" | "decimal_number", similarity: string } { type: "text", id: string, prompt: string, answer: string, similarity: string }], created_millis: int, token: string | null }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /pulls/check changes data

Checks a learner's answers to one pull: one per question in order, or each naming its question's id, so one question can be checked alone. Each mark names its question and has the `type` of its question. An answer to a `number` question is read as an exact number, so 16/5, 3 1/5, 3-1/5, 3⅕, \frac{16}{5} and 3.2 are the same; its mark comes back with the number read, the form it was written in, whether it is correct, and whether it is written the way the question asks. An answer that cannot be read, or is left empty, has no number or form and is not correct. An answer to a `text` question is correct when its words are the answer's, however they are spaced. A question the stream's program wrote its own check for is marked by that check, which may also name the mistake a wrong answer makes, and may accept other answers, asking a judge model about an answer its code cannot decide; the judge's ruling on that answer is kept, so the same answer is asked about once. When the check cannot run, or the judge cannot rule, the check answers 503 and sending it again is safe. Checking changes nothing else.

Request and answers

Body

{
  stream: string,
  key: string,
  answers: [string] | null,
  by_question: [{ question: string, answer: string }] | null
}

Answers

  • 200 { stream: string, key: string, marks: [one of { type: "number", question: string, given: string, value: { numerator: int, denominator: int } | null, written: "as_whole" | "as_fraction" | "as_mixed" | "as_decimal" | null, correct: boolean, as_asked: boolean, expected: string, mistake: "used_addition" | "used_subtraction" | "used_multiplication" | "used_division" | "off_by_one" | "place_value" | "swapped" | "wrong_sign" | "rounding" | "units" | null } { type: "text", question: string, given: string, correct: boolean, as_asked: boolean, expected: string }] }
  • 400, 404, 422, 503 { message: string, status: int, code: string }
POST /pulls/why read only

Shows why one question of an earlier pull is what it is. A question made by code (a stream's skills, or the code the service wrote for a definition) keeps the numbers that code drew for it and any words a model wrote for it, and the service replays them through that code: `steps` lists each number drawn, with the range it was drawn from, and each set of words, with the kind of words asked for, in the order the code took them, and `replay` says whether the replay made the same question again. Its numerals come from the code and its draws (words a model writes hold no digits), and its answer is computed by the code. The code itself is not shown. A question a model wrote at the pull has no steps. `first_pull` names the earlier pull that first served a question this pull served again. Asking changes nothing.

Each account may call this 120 a minute, all its keys together; past that it answers 429 with Retry-After.

Request and answers

Body

{ stream: string, key: string, question: string }

Answers

  • 200 { stream: string, key: string, question: string, steps: [one of { type: "drew", low: int, high: int, value: int } { type: "wrote", kind: "first_name" | "colour" | "animals" | "foods" | "things" | "place", words: string }], replay: "same" | "changed" | "unreplayed" | "unrecorded", first_pull: string | null }
  • 400, 404, 422, 429, 503 { message: string, status: int, code: string }
POST /pulls/check_photo changes data

Checks a learner's answers from a photo of their worksheet for one pull. A model reads what the learner wrote beside each question, as written, and the answers it read are marked as /pulls/check marks them: one mark per question in order, each with the answer read in `given`. A question whose answer was left empty, crossed out or could not be read is marked as unanswered. Send the image as an https: URL or a data:image/ URL; the whole request must be under 1 MiB, so shrink a phone photo first. When the model cannot read the photo, the check answers 503 and sending it again asks the model again. Checking changes nothing but the judge's rulings it keeps, as /pulls/check does.

Each account may call this 60 a minute and 1200 an hour, all its keys together; past that it answers 429 with Retry-After.

Request and answers

Body

{ stream: string, key: string, image: string }

Answers

  • 200 { stream: string, key: string, marks: [one of { type: "number", question: string, given: string, value: { numerator: int, denominator: int } | null, written: "as_whole" | "as_fraction" | "as_mixed" | "as_decimal" | null, correct: boolean, as_asked: boolean, expected: string, mistake: "used_addition" | "used_subtraction" | "used_multiplication" | "used_division" | "off_by_one" | "place_value" | "swapped" | "wrong_sign" | "rounding" | "units" | null } { type: "text", question: string, given: string, correct: boolean, as_asked: boolean, expected: string }] }
  • 400, 404, 422, 429, 503 { message: string, status: int, code: string }
POST /learner/pull read onlytakes a publishable key

Returns the questions of the pull a token names, without their answers, for a page your learners load: it takes your publishable key and the `token` /pulls/create gave the pull, and reaches no other pull.

Each account may call this 240 a minute, all its keys together; past that it answers 429 with Retry-After.

Request and answers

Body

{ token: string }

Answers

  • 200 { stream: string, key: string, questions: [one of { type: "number", id: string, prompt: string, problem: one of { type: "evaluate", operator: "add" | "subtract" | "multiply", operands: [one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int }], layout: "inline" | "stacked" } { type: "convert", numeral: one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int }, form: "improper_fraction" | "whole_number" | "simplest_fraction" | "decimal_number" } { type: "simplify", numeral: one of { type: "integer", value: int } { type: "fraction", numerator: int, denominator: int } { type: "mixed_number", whole: int, numerator: int, denominator: int } } | null, latex: string | null, form: "improper_fraction" | "whole_number" | "simplest_fraction" | "decimal_number" } { type: "text", id: string, prompt: string }] }
  • 400, 404, 422, 429, 503 { message: string, status: int, code: string }
POST /learner/check changes datatakes a publishable key

Checks a learner's answers to the pull a token names, as /pulls/check does, for a page your learners load: it takes your publishable key and the pull's `token`. A mark says whether its answer is correct and written the way the question asks, and may name a wrong answer's mistake, but never gives the question's answer, so a learner cannot read answers off a check of blanks.

Each account may call this 120 a minute and 2400 an hour and 30 a day for each token, all its keys together; past that it answers 429 with Retry-After.

Request and answers

Body

{
  token: string,
  answers: [string] | null,
  by_question: [{ question: string, answer: string }] | null
}

Answers

  • 200 { stream: string, key: string, marks: [one of { type: "number", question: string, given: string, value: { numerator: int, denominator: int } | null, written: "as_whole" | "as_fraction" | "as_mixed" | "as_decimal" | null, correct: boolean, as_asked: boolean, mistake: "used_addition" | "used_subtraction" | "used_multiplication" | "used_division" | "off_by_one" | "place_value" | "swapped" | "wrong_sign" | "rounding" | "units" | null } { type: "text", question: string, given: string, correct: boolean, as_asked: boolean }] }
  • 400, 404, 422, 429, 503 { message: string, status: int, code: string }
POST /learner/check_photo changes datatakes a publishable key

Checks a learner's answers from a photo of their worksheet, as /pulls/check_photo does, for a page your learners load: it takes your publishable key and the pull's `token`. Like /learner/check, a mark never gives the question's answer. Each check calls a model, which your account pays for, so any page holding a pull's token can spend on it.

Each account may call this 10 a minute and 200 an hour and 10 a day for each token, all its keys together; past that it answers 429 with Retry-After.

Request and answers

Body

{ token: string, image: string }

Answers

  • 200 { stream: string, key: string, marks: [one of { type: "number", question: string, given: string, value: { numerator: int, denominator: int } | null, written: "as_whole" | "as_fraction" | "as_mixed" | "as_decimal" | null, correct: boolean, as_asked: boolean, mistake: "used_addition" | "used_subtraction" | "used_multiplication" | "used_division" | "off_by_one" | "place_value" | "swapped" | "wrong_sign" | "rounding" | "units" | null } { type: "text", question: string, given: string, correct: boolean, as_asked: boolean }] }
  • 400, 404, 422, 429, 503 { message: string, status: int, code: string }
POST /chat/completions changes data

Defines a stream by conversation, in the OpenAI Chat Completions shape, so an OpenAI client pointed at this API can send it. `model` names the stream to define, as `stream:maya` names the stream whose slug is maya, and `messages` is the whole conversation so far. A message's content is a string or a list of text and image parts, and a user message may carry images (https: or data:image/ URLs), such as a worksheet to match. The other request fields a client sends with them, such as `temperature` or `max_tokens`, are accepted and ignored, except a request for a streamed answer, for a number of choices other than one, or for log probabilities, which is refused. The assistant asks a question back when it needs one. Once it knows what you want it writes the stream's definition, which creates the stream or makes its next revision, and `stream` names it. A turn takes a few seconds. A new definition is saved at once, and its `program` is `writing`: the service then writes the code that makes its questions, and checks a sample of them with a second solver, in up to six rounds, the writer fixing its program after each the service sends back. That takes about half a minute, and longer when a draft is sent back; until it ends a pull of the stream answers 503 try_again, and /streams/writing shows each draft so far. Once writing ends, the revision's `program` on /streams/get says what it runs: the code, or no code and why, in which case its pulls are written by a model. A definition the same as the current one changes nothing.

Request and answers

Body

{
  model: string,
  messages: [{
    role: "system" | "user" | "assistant",
    content: string | [one of
      { type: "text", text: string }
      { type: "image_url", image_url: { url: string } }]
  }],
  stream: boolean | null,
  n: int | null,
  logprobs: boolean | null,
  top_logprobs: int | null,
  temperature: any JSON,
  top_p: any JSON,
  frequency_penalty: any JSON,
  presence_penalty: any JSON,
  max_tokens: int | null,
  max_completion_tokens: int | null,
  seed: int | null,
  stop: string | [string] | null,
  user: string | null,
  safety_identifier: string | null,
  prompt_cache_key: string | null,
  prompt_cache_retention: string | null,
  service_tier: string | null,
  reasoning_effort: string | null,
  verbosity: string | null,
  store: boolean | null,
  parallel_tool_calls: boolean | null,
  metadata: any JSON,
  logit_bias: any JSON,
  stream_options: any JSON
}

Answers

  • 200 { id: string, object: string, created: int, model: string, choices: [{ index: int, message: { role: "system" | "user" | "assistant", content: string }, finish_reason: string }], stream: { slug: string, title: string, revision: int } | null, program: one of { type: "runs", program_hash: string } { type: "not_written", sent_back: [{ problems: [string] }], failed: { step: "writer_call" | "compiling" | "words_call" | "solver_call", reason: string } | null } { type: "by_skills" } { type: "writing" } { type: "replaced" } | null }
  • 400, 404, 422, 503 { message: string, status: int, code: string }

Skills

Instead of a conversation, a stream can be a list of these skills, sent to /streams/create; its questions come from the engine’s own generators, with no model call. Each skill is sent as an object whose type names the skill, with its limits as fields.

SkillSent asWhat it asks
mixed_to_improper{ type: "mixed_to_improper", max_whole: int, denominators: [int] }Write a mixed number such as 3 1/5 as an improper fraction. The whole part is at most max_whole and the denominator comes from your list.
add_whole{ type: "add_whole", digits: int, regroup: boolean }Add two whole numbers with the given number of digits. regroup says whether some column carries.
subtract_whole{ type: "subtract_whole", digits: int, regroup: boolean }Subtract two whole numbers with the given number of digits, the first larger. regroup says whether some column borrows.
simplify_fraction{ type: "simplify_fraction", max_denominator: int }Simplify a fraction such as 6/8. The unsimplified denominator is at most max_denominator.
to_decimal{ type: "to_decimal", max_whole: int, denominators: [int] }Write a mixed number such as 9 1/10 as a decimal. Every denominator in your list must give a decimal that ends.