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.
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.
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.
Status
auth_reason
What it means
What to do
401
missing_bearer
The call has no Authorization header.
Add -H 'Authorization: Bearer YOUR_API_KEY' with your key in place of YOUR_API_KEY.
401
invalid_api_key
The 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.
401
sign_in_ended
An 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.
401
revoked_api_key
The key was revoked on the account page.
Make a new key.
401
expired_api_key
The key had an expiry date, and it has passed.
Make a new key.
403
publishable_key_not_allowed
A publishable key called an endpoint that takes only an API key.
Make this call from your server with your API key.
503
api_key_check_unavailable
The 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"
}
}
}
}
A pull has no duplicate prompts. Selection prefers fresh questions and separates similar ones when possible. A small skill definition may produce fewer questions than requested, and later pulls may repeat earlier questions: a new key on a stream defined by conversation may serve again, for up to half its count, questions a model call paid for in earlier pulls of the same revision, none among the last 60 the stream served. Use pull.questions.length as the number served.
Retry with the same stream, key and count. A new key takes another set. Another count under a key already pulled is refused with 422; the original set stays. Keys belong to a stream under the caller’s identity.
Check value and form separately.correct tests the number; as_asked tests how it was written. Use correct && as_asked when both matter: a wrong decimal can still be in the requested decimal form. When a stream’s program wrote a question its own check, a wrong answer’s mistake may name what went wrong, such as used_addition; otherwise it is null. Checking does not store learner marks.
A 200 is the answer itself; anything else is a refusal. A refusal is an HTTP status with a body of message and status. A 503 means the service could not settle the request just now, and sending the same request again is safe. For a stream defined by conversation, a pull also answers 503 when its questions could not be made just now; nothing is saved, so the key is still free. The API reference lists the statuses each endpoint can give.
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/listread only
Lists your streams with each one's current revision.
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.
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.
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.
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 }
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.
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.
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.
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.
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.
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.
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 }]
}
POST/learner/checkchanges 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.
POST/learner/check_photochanges 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.
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
}
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.