Generate reasoning items, from a seed, over HTTP

# five logic items, a seed chosen for you and returned
curl -s 'https://mytestatlas.com/api/items?kind=logic&count=5'

How items are checked

Each request creates a set of questions with one checked answer per question. The seed and generator version let you reproduce the same set for review.

The families

Item families available through the API. GET /api/items/families returns it as JSON.

figure-matrix · matrix

Figure matrices

3 × 3 grids of drawn figures with one cell missing; exactly one option is proved to fit every rule.

figure-series · series

Figure series

Four drawn figures in a row; exactly one option continues the rule.

rotation · spatial

Mental rotation

Which option is the figure turned by the stated angle?

mirror · spatial

Mirror images

Which option is the figure mirrored left to right?

syllogism · logic

Syllogisms

Two premises over invented categories; which conclusion follows? Checked against all 256 ways three sets can overlap.

propositional · logic

Propositional logic

Statements about P, Q and R; which must be true? Checked against all 8 rows of the truth table.

ordering · logic

Ordering puzzles

Five invented names in a row and a few clues; which place does one of them take? Checked against all 120 arrangements.

verbal · aptitude

Verbal reasoning

A passage about invented organisations and a statement: true, false or cannot say, keyed over every situation the passage leaves open.

numerical · aptitude

Numerical reasoning

Read a table and compute one figure; the wrong options are what the usual mistakes produce.

sudoku · puzzle

Sudoku

4 × 4, 6 × 6 and 9 × 9 grids with exactly one solution, graded by the techniques a logical solver needed.

nonogram · puzzle

Nonograms

Picture grids from row and column run lengths, 5 × 5 to 15 × 15, each proved solvable by line logic alone — so unique and guess-free.

calcudoku · puzzle

Calcudoku

Latin squares behind arithmetic cages (+ − × ÷), 4 × 4 to 6 × 6, each with exactly one solution proved by a solver.

logic-grid · puzzle

Logic grid puzzles

Zebra-style puzzles in plain English, 3 × 3 to 5 × 5, each proved to have one solution by a solver that never guesses, with its deduction chain.

knights-knaves · logic

Knights and knaves

Island puzzles of truth-tellers and liars, 2–5 speakers; exactly one consistent assignment, proved over the whole truth table.

number-series · series

Number series

What number comes next: arithmetic to interleaved and recursive rules, unique under a stated rule grammar, with near-rule distractors.

letter-series · series

Letter series

What comes next in a series of letters or letter groups, with wrap-around counting; unique under a stated rule grammar.

belief-bias · logic

Belief-bias syllogisms

Syllogisms about real categories whose validity and believability disagree; validity proved over all 256 models.

bayes · reasoning

Base-rate problems

Screening, witness, spam and inspection problems with an exact Bayesian answer and computed base-rate-neglect lures.

reflection · reasoning

Reflection puzzles

Short everyday number problems with a tempting first answer; the lure is computed from the same numbers as the key.

wason · reasoning

Selection tasks

Four cards and a rule: which cards must be turned to test it? Everyday rules and abstract ones, with negations.

conjunction · reasoning

Conjunction problems

A short description of an invented person, then: which statement is more probable? A single event always beats its conjunctions.

covariation · reasoning

Covariation tables

2 × 2 contingency tables: does the treatment help? Keyed by the exact ΔP, with the big-cell lure computed.

Ask for items

# the same five, forever
curl -s 'https://mytestatlas.com/api/items?kind=logic&count=5&seed=2026'

Fields: kind is matrix, series, spatial, logic, aptitude, puzzle, reasoning; count is 1 to 50; seed is any integer, and is returned whether you sent one or not; family narrows the item types, comma-separated; generator is 2 unless you ask for 1.

Generator versions. The same seed and generator version return the same items forever, and every figure response names its generator. Generator 2 (from 25 September 2026) builds each figure item's options as a balanced set, so they cannot be answered by picking the option most like the others; under generator 1 that shortcut found the key in over 90% of matrix and series items. generator=1 still rebuilds any earlier seed exactly. The logic items have one generator.

Use GET. Every endpoint here takes a query string. A POST with a JSON body also works, but only with an x-amz-content-sha256 header holding the SHA-256 of that body, because the CDN in front of the API signs requests to the origin.

What comes back

Every item carries its id, family, question, lettered options, the answer letter, and checkedAgainst: how many candidate answers were enumerated to prove this one is the only one that fits. Every item carries why, the rule in words (for a figure item, the family's rule on generator 2; generator 1 left it null). Logic items add prompt, the item already formatted as the text you would send a model. Figure items carry stem and a per-option figure as inline SVG, and the same item described in text.

Mark the answers

# send the letters back with the seed they came from
curl -s 'https://mytestatlas.com/api/score?kind=logic&seed=2026&answers=C,C,B'

Send the same family and generator the items call used; the paper is rebuilt from them and the seed rather than stored, so nothing about you is kept between the two requests. You get each item marked with the rule, and correctOfSet: right answers out of this set, which is not a percentile and not an IQ.

Whole tests: forms

A form is a complete test drawn from the same generator: a preset or your own mix of kinds and families, a time limit and a seed. Grading returns the number correct, a chance-adjusted score (guessing scores 0, a perfect paper 100), a breakdown per kind and per family, and every key with its rule.

# draw a preset
curl -s 'https://mytestatlas.com/api/forms?preset=reasoning-20'

# grade it: one letter per item in order, empty for skipped
curl -s 'https://mytestatlas.com/api/forms/<formId>/grade?answers=B,C,,A&tookSeconds=640'

Presets: reasoning-20, logic-15, figures-24 and full-mix-40; GET /api/forms/presets lists their mixes. Drawing a form costs its item count; grading costs one.

Verify an answer

Send the recipe and the answer; the item is regenerated from the recipe and marked, never taken from the caller, so a forged key cannot pass. A single check or up to 20 in one POST; four checks cost one unit. Verify comes with the Research and Lab plans; other callers get a 402 plan_required with a link to the pricing page.

# mark one answer against its recipe
curl -s 'https://mytestatlas.com/api/verify?family=sudoku&seed=1&difficulty=2&answer=562913487479826351813547962248659713936178524157432698621794835785361249394285176' \
  -H 'X-Api-Key: sfk_live_…'

Every registry family takes difficulty (1 to 5, where the family has that level) and its own params: GET /api/families lists both, per family. Grid puzzles answer with the grid as one string, row by row.

Hints (beta)

Add hints=1 and every item carries hints: three rungs, where to look, the rule and the worked solution, and a whyNot line for each wrong option. The first two rungs never name the answer, and the worked solution ends by describing the missing term or tile rather than its letter, so your own interface decides when to show the key. hintRegister=plain gives shorter sentences in plainer words.

Hints come with number and letter series at every difficulty, and with figure grids and series at generator 2 when you name the rule: rule on figure-matrix and figure-series, or family on kind=matrix and kind=series, and with logic: syllogism, propositional and ordering, or kind=logic. Each wrong logic option gets its own counter-case: a picture of the groups, a row of true and false, or, for an ordering place, usually the one, two or three clues that rule it out, or the steps that follow from trying the name there (about one ordering why-not in twenty says only that no order with the name there fits every clue). Every logic item is hinted, including syllogisms of the form “Some M are not P; all M are S” and ordering puzzles with no clue that fixes a place. If an item ever cannot be hinted, it keeps its place, so a seed always returns the same items, with "hints": null and "hintsUnavailable": {"code": "hints_unsupported_item", "detail": "…"}; today no logic item does. Turning shapes, other puzzles and generator 1 have no hints yet; such a request is refused with hints_unsupported_family, which lists what is hinted, before anything is counted. Hints cost no extra units, are CC0 like the items, and come with the Trial, Research and Lab plans.

Each question includes three hints: two clues followed by a worked explanation. Asking for hints stores nothing more: the call is counted like any other, and whether it asked for hints is not recorded.

# one number series with its hints
curl -s 'https://mytestatlas.com/api/items?family=number-series&difficulty=2&count=1&seed=2026&hints=1' \
  -H 'X-Api-Key: sfk_live_…'

{
  "family": "number-series",
  "seed": 2026,
  "difficulty": 2,
  "prompt": "What number comes next?\n4, 12, 36, 108, 324, 972, …",
  "options": [
    {
      "letter": "A",
      "text": "2052"
    },
    {
      "letter": "B",
      "text": "612"
    },
    {
      "letter": "C",
      "text": "1620"
    },
    {
      "letter": "D",
      "text": "2916"
    }
  ],
  "answer": "D",
  "hints": {
    "library": "2026-10-17.8ea0347d",
    "register": "std",
    "rungs": [
      {
        "rung": 1,
        "name": "where-to-look",
        "text": "Cover everything but the first two terms. How did you get from one to the other?"
      },
      {
        "rung": 2,
        "name": "the-rule",
        "text": "From 4 → 12, each term is multiplied by 3. Check that every pair uses it, then apply it to the last term."
      },
      {
        "rung": 3,
        "name": "worked-solution",
        "text": "Check the multiplier on the last pair: it is still 3. Apply it once more to the end of 324, 972: 972 × 3 = 2916. Now find it among the options."
      }
    ],
    "whyNot": {
      "A": "Option A fits only the last few terms; across the whole list each term multiplies the one before by the same number.",
      "B": "Option B continues every other term at a fixed gap; the rule for every term gives another number.",
      "C": "Option C just extends the final step. Look at the earlier steps: they are not all the same size."
    }
  }
}

Printable worksheets

A worksheet is an A4 PDF of any family's items with the answer key on its own page, built in the browser from the same generators and the same seeds as the API, so a worksheet and an API call with the same recipe hold the same items. Nothing is uploaded. Build one on the examples page: a six-item sample for anyone, your own sets with Maker and above during the beta.

Status codes and errors

Every answer under /api/ is JSON with a code. Key on code, not on the status alone.

Keys, limits and plans

Every call works without a key in the playground. Sign in at /account/ for a key, and send it as X-Api-Key (the CDN writes its own signature into Authorization, so a bearer token would be overwritten). The limits below are read from the plan table the API meters with.

# the same call, with a key
curl -s 'https://mytestatlas.com/api/items?kind=logic&count=5' \
  -H 'X-Api-Key: sfk_live_…'

Prices are in USD, excl. tax. Billing starts when the beta ends; we email you first; nothing is charged without your confirmation. Item API pricing: compare the plans.

The cost of a call is the number of items it produces or marks. Metered responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and keyed calls add X-Quota-Limit, X-Quota-Used, X-Quota-Remaining and X-Quota-Month.

Running an evaluation without spoiling it

1. Publish the seeds after the run, never before. Report the seed range with your results so anyone can rebuild every item and check your marking.
2. Use a seed range once. A range you have already published may be in a training set by the time you run again.

Use the logic kind for text-only models: 20,000 seeds produced 20,000 distinct syllogisms and 19,707 distinct ordering puzzles. Atlas Eval runs this for you from a secret seed, grades once, and ranks the result on a public board. The item API keeps no leaderboard, because a number without its seed range cannot be checked by anybody; the ranked boards are Atlas Eval and the daily challenge, and each publishes its seed with the grade.

Compared with reasoning-gym

reasoning-gym is an open-source Python library of procedural reasoning-task generators with answer checkers, which you install and run yourself. It is the right choice when you want the generators inside your own training loop. This API is the other shape of the same idea:

From an agent: the MCP server

The same endpoints are wrapped as an MCP server: one file with no dependencies, served from this site. It works without a key at the playground limits, and takes one through the MYTESTATLAS_API_KEY environment variable.

Download the server — one file, no dependencies — and register it with your client; you can read all of it before you run it.

# fetch the server file from this site
curl -fsSO https://mytestatlas.com/developers/mytestatlas-mcp.mjs

# register it (Claude Code shown; any MCP client runs the same command)
claude mcp add mytestatlas -- node ./mytestatlas-mcp.mjs

Other clients take the same command in their JSON configuration:

{
  "mcpServers": {
    "mytestatlas": {
      "command": "node",
      "args": [
        "/path/to/mytestatlas-mcp.mjs"
      ],
      "env": {
        "MYTESTATLAS_API_KEY": "sfk_live_…"
      }
    }
  }
}

Terms, plainly

Items generated from a public seed are released under CC0: use them commercially, publish them, train on them. What we ask in return is honesty about what they are: original items with published rules, not a normed intelligence test. Do not present a score from this API to anyone as an IQ. The terms cover the paid plans and the items licensed to an account.

What is stored about a request is a counter: per key, items this minute and this month; per anonymous caller, the same under a one-way hash of the address that expires within two days. No key is stored in readable form, and nothing records what you generated.

Something wrong here, or a kind of item you want and cannot get? support@mytestatlas.com.