Examples

A recorded run of the API over a few days of one learner’s practice, and apps built on it whose source you can read. The docs explain each call.

A few days of practice

Step through a recorded example of defining a stream in a conversation, retrying a pull, changing the stream and checking answers. These calls ran against the compiled program when the page was built, with one stand-in: the build has no model, so the assistant’s replies and the code it writes for each definition are examples written for this page. Everything else, down to each question’s prompt, LaTeX and answer, is what the engine answered by running that code. The controls replay that recording; they do not send requests to the live API.

Your appuser: sam
No stream yet
Pulls appear here.

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

  1. 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.

    You send

    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."}]}'

    You get back

    {
      "id": "gen-example-1",
      "object": "chat.completion",
      "created": 1794951392,
      "model": "stream:maya",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "I made Maya fractions: half the questions turn a mixed number into an improper fraction, and half simplify a fraction."
          },
          "finish_reason": "stop"
        }
      ],
      "stream": {
        "slug": "maya",
        "title": "Maya fractions",
        "revision": 1
      },
      "program": {
        "type": "writing"
      }
    }
  2. 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.

    You send

    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}'

    You get back

    {
      "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
    }
  3. 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.

    You send

    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}'

    You get back

    {
      "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": true
    }
  4. The next day's pull takes six new questions, and none of the first day's is served again.

    You send

    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-30","count":6}'

    You get back

    {
      "pull": {
        "stream": "maya",
        "key": "2026-09-30",
        "revision": 1,
        "requested": 6,
        "questions": [
          {
            "type": "number",
            "id": "1-15",
            "prompt": "Simplify 3/9.",
            "problem": null,
            "latex": "\\text{Simplify } \\frac{3}{9}",
            "answer": {
              "numerator": 1,
              "denominator": 3
            },
            "answer_text": "1/3",
            "form": "simplest_fraction",
            "similarity": "written/simplifying"
          },
          {
            "type": "number",
            "id": "1-20",
            "prompt": "Write 4 3/8 as an improper fraction.",
            "problem": null,
            "latex": "4\\tfrac{3}{8}",
            "answer": {
              "numerator": 35,
              "denominator": 8
            },
            "answer_text": "35/8",
            "form": "improper_fraction",
            "similarity": "written/improper fractions"
          },
          {
            "type": "number",
            "id": "1-22",
            "prompt": "Simplify 4/12.",
            "problem": null,
            "latex": "\\text{Simplify } \\frac{4}{12}",
            "answer": {
              "numerator": 1,
              "denominator": 3
            },
            "answer_text": "1/3",
            "form": "simplest_fraction",
            "similarity": "written/simplifying"
          },
          {
            "type": "number",
            "id": "1-30",
            "prompt": "Write 5 1/3 as an improper fraction.",
            "problem": null,
            "latex": "5\\tfrac{1}{3}",
            "answer": {
              "numerator": 16,
              "denominator": 3
            },
            "answer_text": "16/3",
            "form": "improper_fraction",
            "similarity": "written/improper fractions"
          },
          {
            "type": "number",
            "id": "1-31",
            "prompt": "Simplify 8/12.",
            "problem": null,
            "latex": "\\text{Simplify } \\frac{8}{12}",
            "answer": {
              "numerator": 2,
              "denominator": 3
            },
            "answer_text": "2/3",
            "form": "simplest_fraction",
            "similarity": "written/simplifying"
          },
          {
            "type": "number",
            "id": "1-33",
            "prompt": "Write 3 5/8 as an improper fraction.",
            "problem": null,
            "latex": "3\\tfrac{5}{8}",
            "answer": {
              "numerator": 29,
              "denominator": 8
            },
            "answer_text": "29/8",
            "form": "improper_fraction",
            "similarity": "written/improper fractions"
          }
        ],
        "created_millis": 1794951430277,
        "token": "67OuVYftYVPj04RezLluorUUQhsMRNKW"
      },
      "replayed": false
    }
  5. Maya is ready for decimals, so the app continues the conversation, sending all of it again. The assistant asks one question back and saves nothing yet, so stream is null.

    You send

    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."},{"role":"assistant","content":"I made Maya fractions: half the questions turn a mixed number into an improper fraction, and half simplify a fraction."},{"role":"user","content":"Maya is ready for decimals."}]}'

    You get back

    {
      "id": "gen-example-5",
      "object": "chat.completion",
      "created": 1794951430,
      "model": "stream:maya",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Should the decimals replace the fractions, or join them?"
          },
          "finish_reason": "stop"
        }
      ],
      "stream": null,
      "program": null
    }
  6. The app sends the answer. The new definition makes revision 2, and its new code is written after the turn answers; pulls made before it keep their questions.

    You send

    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."},{"role":"assistant","content":"I made Maya fractions: half the questions turn a mixed number into an improper fraction, and half simplify a fraction."},{"role":"user","content":"Maya is ready for decimals."},{"role":"assistant","content":"Should the decimals replace the fractions, or join them?"},{"role":"user","content":"Replace them: fractions and mixed numbers to write as decimals, with whole parts up to 5 and denominators 2, 4, 5 and 10."}]}'

    You get back

    {
      "id": "gen-example-6",
      "object": "chat.completion",
      "created": 1794951430,
      "model": "stream:maya",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Maya's stream now asks for decimals: fractions and mixed numbers with denominators 2, 4, 5 and 10, written as decimals."
          },
          "finish_reason": "stop"
        }
      ],
      "stream": {
        "slug": "maya",
        "title": "Maya decimals",
        "revision": 2
      },
      "program": {
        "type": "writing"
      }
    }
  7. The following day's pull comes from revision 2.

    You send

    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-10-01","count":6}'

    You get back

    {
      "pull": {
        "stream": "maya",
        "key": "2026-10-01",
        "revision": 2,
        "requested": 6,
        "questions": [
          {
            "type": "number",
            "id": "2-0",
            "prompt": "Write 5 7/10 as a decimal.",
            "problem": null,
            "latex": "5\\tfrac{7}{10}",
            "answer": {
              "numerator": 57,
              "denominator": 10
            },
            "answer_text": "5.7",
            "form": "decimal_number",
            "similarity": "written/decimals"
          },
          {
            "type": "number",
            "id": "2-11",
            "prompt": "Write 3 1/2 as a decimal.",
            "problem": null,
            "latex": "3\\tfrac{1}{2}",
            "answer": {
              "numerator": 7,
              "denominator": 2
            },
            "answer_text": "3.5",
            "form": "decimal_number",
            "similarity": "written/decimals"
          },
          {
            "type": "number",
            "id": "2-22",
            "prompt": "Write 5 3/5 as a decimal.",
            "problem": null,
            "latex": "5\\tfrac{3}{5}",
            "answer": {
              "numerator": 28,
              "denominator": 5
            },
            "answer_text": "5.6",
            "form": "decimal_number",
            "similarity": "written/decimals"
          },
          {
            "type": "number",
            "id": "2-34",
            "prompt": "Write 3/5 as a decimal.",
            "problem": null,
            "latex": "\\frac{3}{5}",
            "answer": {
              "numerator": 3,
              "denominator": 5
            },
            "answer_text": "0.6",
            "form": "decimal_number",
            "similarity": "written/decimals"
          },
          {
            "type": "number",
            "id": "2-49",
            "prompt": "Write 2 1/5 as a decimal.",
            "problem": null,
            "latex": "2\\tfrac{1}{5}",
            "answer": {
              "numerator": 11,
              "denominator": 5
            },
            "answer_text": "2.2",
            "form": "decimal_number",
            "similarity": "written/decimals"
          },
          {
            "type": "number",
            "id": "2-50",
            "prompt": "Write 4 1/5 as a decimal.",
            "problem": null,
            "latex": "4\\tfrac{1}{5}",
            "answer": {
              "numerator": 21,
              "denominator": 5
            },
            "answer_text": "4.2",
            "form": "decimal_number",
            "similarity": "written/decimals"
          }
        ],
        "created_millis": 1794951464073,
        "token": "mk71dSl0M9hbmjGggkQbC0hPpZxaGywZ"
      },
      "replayed": false
    }
  8. The first day's questions are still there under their key, unchanged by the revision.

    You send

    curl -X POST 'https://api.problemsapi.com/pulls/get' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'content-type: application/json' \
      -d '{"stream":"maya","key":"2026-09-29"}'

    You get back

    {
      "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"
    }
  9. The history lists every pull with the revision it came from.

    You send

    curl -X POST 'https://api.problemsapi.com/pulls/history' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'content-type: application/json' \
      -d '{"stream":"maya"}'

    You get back

    {
      "stream": "maya",
      "pulls": [
        {
          "key": "2026-10-01",
          "revision": 2,
          "requested": 6,
          "served": 6,
          "created_millis": 1794951464073
        },
        {
          "key": "2026-09-30",
          "revision": 1,
          "requested": 6,
          "served": 6,
          "created_millis": 1794951430277
        },
        {
          "key": "2026-09-29",
          "revision": 1,
          "requested": 6,
          "served": 6,
          "created_millis": 1794951430235
        }
      ]
    }
  10. Maya does the 1 October questions on paper and the app sends what she wrote. She wrote one answer as a fraction instead of a decimal, which is the right number but not the form asked for; one answer is wrong and one is blank.

    You send

    curl -X POST 'https://api.problemsapi.com/pulls/check' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'content-type: application/json' \
      -d '{"stream":"maya","key":"2026-10-01","answers":["5.7","7/2","5.6","1.6","2.2",""]}'

    You get back

    {
      "stream": "maya",
      "key": "2026-10-01",
      "marks": [
        {
          "type": "number",
          "question": "2-0",
          "given": "5.7",
          "value": {
            "numerator": 57,
            "denominator": 10
          },
          "written": "as_decimal",
          "correct": true,
          "as_asked": true,
          "expected": "5.7",
          "mistake": null
        },
        {
          "type": "number",
          "question": "2-11",
          "given": "7/2",
          "value": {
            "numerator": 7,
            "denominator": 2
          },
          "written": "as_fraction",
          "correct": true,
          "as_asked": false,
          "expected": "3.5",
          "mistake": null
        },
        {
          "type": "number",
          "question": "2-22",
          "given": "5.6",
          "value": {
            "numerator": 28,
            "denominator": 5
          },
          "written": "as_decimal",
          "correct": true,
          "as_asked": true,
          "expected": "5.6",
          "mistake": null
        },
        {
          "type": "number",
          "question": "2-34",
          "given": "1.6",
          "value": {
            "numerator": 8,
            "denominator": 5
          },
          "written": "as_decimal",
          "correct": false,
          "as_asked": true,
          "expected": "0.6",
          "mistake": null
        },
        {
          "type": "number",
          "question": "2-49",
          "given": "2.2",
          "value": {
            "numerator": 11,
            "denominator": 5
          },
          "written": "as_decimal",
          "correct": true,
          "as_asked": true,
          "expected": "2.2",
          "mistake": null
        },
        {
          "type": "number",
          "question": "2-50",
          "given": "",
          "value": null,
          "written": null,
          "correct": false,
          "as_asked": false,
          "expected": "4.2",
          "mistake": null
        }
      ]
    }
  11. The app asks how the fourth question, the one Maya got wrong, was made. The answer lists the numbers the stream's code drew for it, oldest first, each with the range it was drawn from. The service runs the code again on those numbers and gets the same question back, so replay is same. Asking changes nothing.

    You send

    curl -X POST 'https://api.problemsapi.com/pulls/why' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -H 'content-type: application/json' \
      -d '{"stream":"maya","key":"2026-10-01","question":"2-34"}'

    You get back

    {
      "stream": "maya",
      "key": "2026-10-01",
      "question": "2-34",
      "steps": [
        {
          "type": "drew",
          "low": 0,
          "high": 5,
          "value": 0
        },
        {
          "type": "drew",
          "low": 1,
          "high": 4,
          "value": 3
        },
        {
          "type": "drew",
          "low": 1,
          "high": 4,
          "value": 3
        }
      ],
      "replay": "same",
      "first_pull": null
    }

Apps built on the API

6problems

Six practice questions a day for a parent to print or share. Each day’s set is a pull whose key is the date, so reopening the day gives the same six questions.

Times tables flashcards

Flashcards to 12 × 12 with a five-second timer and scoreboards shared by an invite link. Its server makes each deck with a secret key; the browser reads the questions and checks answers with a publishable key and the pull’s token. The source is written to be read.