A small JSON API. Reading needs nothing; writing needs a key, and an account whose edits have been reviewed. The numberdb package is the supported way to use all of this — it handles the response format, the retries and the crash-safety — and this page is what it is built on.
Anonymous use is limited to 60 requests per hour; a key raises it to 1000. Send it as a bearer token, and keep it out of a worksheet you might share:
export NUMBERDB_API_KEY=... curl -H "Authorization: Bearer $NUMBERDB_API_KEY" https://numberdb.org/api/table?id=T7
Exceeding the limit returns 429 with a Retry-After header.
Create your own key on the API keys page.
A valid key permits read access to the draft listing even without API write
permission; it does not permit reading another contributor's draft contents.
Writing needs more than a key. It opens once 5 of the account's edits have been reviewed and accepted — edits made on the site count. A person editing one table exercises judgement about it; a program exercises none and writes faster than anyone can read, so the gate is a track record that a script cannot manufacture for itself.
Writing also enforces the size limits rather than warning about them, and refuses a document whose type or parameters do not make sense. A person over a soft limit is told and their edit is saved; a program is refused until the reason is in the document, because a warning shown to nobody is not a limit.
The complete lightweight catalogue, ordered by numeric T-number and generated from the website database. No entries, attachments or table definitions are downloaded. POST to this same URL still creates a table.
| limit | page size, from 1 to 500; default 100 |
|---|---|
| after | omit for the first page, which includes T0; use the returned next_after for the next page (strictly after that numeric T-number) |
| include_drafts | 1 adds draft listings; requires a valid API key or signed-in session, not write permission. Default 0 |
| returns | tables and next_after; a null cursor means there are no further rows |
Each record has tid, title, canonical
url, created_by, updated_at and
status (published, in_progress, or
offered_for_review). Published records also have
tags, revision, reviewed_revision
and review_status (reviewed, unreviewed,
or unknown). Revisions contain an id and content
digest, or are null when unavailable. An empty draft may have
no modification timestamp. Draft listings omit tags and revision details,
including when read by their author.
updated_at is the head revision's creation time. An ongoing
generator run can amend that revision without changing its date; use
ETags and revision digests, not timestamps alone, to detect updates.
curl 'https://numberdb.org/api/tables?limit=100' curl -H "Authorization: Bearer $NUMBERDB_API_KEY" \ 'https://numberdb.org/api/tables?include_drafts=1&limit=100'
Walk every page to enumerate the catalogue. Pagination is a live walk,
not an atomic snapshot: refresh before creating a draft. These read
endpoints support HEAD and conditional GET using ETag and
If-None-Match. Cached responses are private and must be
revalidated; never share an authenticated cache with other users.
Read a candidate table's definition and conventions without its entries
or attachment contents. The response contains a catalogue record and a
metadata mapping with the available sections: Title,
Definition, Parameters, Comments, Formulas, References, Links, Similar
tables, Data properties and Tags. Absent sections are omitted.
files maps attached filenames to SHA-256 digests, without
downloading their contents. review_token identifies the current
revision content and complete attachment manifest; it also changes for
in-place run amendments. It can guard a later review offer.
Published tables are public. Draft metadata requires the author's or a board member's key or login; other readers receive 404. Listing a draft does not grant access to its contents.
Discovery only: this is a partial document and mapping order is not preserved. Fetch the full table before preparing an edit; never send metadata back as a replacement table. A matching title or number is not proof of duplication: compare definitions, conventions and coverage.
curl https://numberdb.org/api/table/T7/metadata
The Python and Sage clients expose list_tables() (a lazy,
automatically paginated iterator of dicts) and table_metadata("T7").
If an installed client does not yet have these helpers, use the REST
endpoints directly rather than fetching every full table.
Search by number, by expression or by words. This is what the search bar uses.
| q | the term: a decimal, a fraction, a p-adic, a polynomial, an expression such as pi, or words |
|---|---|
| returns | matching numbers, and the tables and tags whose text matched |
Values held too imprecisely to identify anything, and values nobody has reviewed, are left out of search by number and marked on their table instead. A reader looking at a table can weigh an unconfirmed entry; somebody typing digits cannot, because a wrong fortieth digit looks exactly like a right one.
Look up a number whose type you already know, given its components, or several at once.
| kind | ZZ, QQ, RIF, RBF, CIF, Qp, polynomial |
|---|---|
| returns | the matching entries, keyed by position when several were asked about |
At most 100 numbers per call. Every position asked about is present in the answer, so a number that matched nothing maps to an empty list rather than being absent.
One table, whole.
| id | its T-number, e.g. T7 |
|---|---|
| url | or its slug |
| returns | the document: its prose, its parameters and its entries |
A draft requires its author's or a board member's API key; other callers receive a missing-table response. To discover work in progress without its contents, use the authenticated catalogue.
One tag, and what carries it.
| url | the tag, e.g. elliptic+curves |
|---|---|
| returns | its canonical name, how many published tables and numbers carry it, and which tables |
Approved synonyms resolve to the canonical name. Public tags also expose
concept: reviewed description, aliases, broader/narrower topics,
references and the accepted revision identifier (null before first approval).
Propose concept changes from the tag page; they require separate board review
and do not change table memberships.
The checks a table is read against, run on one table.
| tid | in the path, e.g. T7 |
|---|---|
| returns | findings, a list of sentences, and clean, true when that list is empty |
These are the same checks as manage.py
audit_table, through the same implementation, for a machine that
computes a table but holds no copy of the database. A finding is a thing to
look at, not a verdict: the rules are rules, and one of them can be right
in form and wrong here. Outward links are not followed — that is the
command’s --links, and it needs a database. A draft
answers to a key that may see it, and otherwise as though it did not
exist.
This page.
Every content upload must send X-Engine and X-Model:
the AI agent/tool and actual model, or explicitly none for both
when no AI assisted the contribution. This applies to new tables, full-document
and entry-only edits, and attached files. Missing or partial declarations,
placeholders, and values over 80 printable characters return HTTP 400 with
code: invalid_agent_provenance. Historical missing information stays
“Not recorded”, not “No AI agent used”. These are declarations by the submitter,
not independently verified provider identities.
The Python package reads NUMBERDB_ENGINE and
NUMBERDB_MODEL; direct callers send the corresponding headers.
NUMBERDB_ASSISTED_BY or producer text alone does not replace them.
Use a new X-Run-Id when the agent/model changes; a run cannot be
reused by another account. Reads, leases and review offers need no declaration.
Add a table. The body is the whole document, as YAML or JSON.
| X-Draft | yes creates the table unpublished and in progress, ready creates it and offers it for review at once: invisible, in no listing, answering no search, and publishable later by somebody who has looked at it. Creating a published table with a program is board-only, because a table is a permanent number and a parameter order that citations resolve on; a draft is neither yet. An account may hold a few drafts at once, and the answer reports drafts_held and drafts_remaining |
|---|---|
| X-Numberdb-Client | which client this is, as name/version. The numberdb package sends numberdb-python/<version> and the revision records that it arrived through the package; a request without it is recorded as having come through the API directly. A different fact from X-Produced-By, which says what made the values: the same generator run from a laptop and pasted into the form on the site agree about what, and differ about how |
| X-Produced-By | what made this, recorded on the revision and shown in its history. Defaults to api. The numberdb package sends the generator and the versions of the package and of Sage, and — when NUMBERDB_ASSISTED_BY is set — whatever ran the publish: Zeta (numberdb=0.1.2, sage=10.9), assisted by Claude Code, table-build@8390298. Name each layer that can change without you noticing, at a version: there is rarely one thing that made a revision, and numberdb=0.1.2, sage=10.9 is the same habit applied to the generator. Record the actual model reported by your session in the required structured headers; resolve uncertainty before uploading, rather than guessing and do not cite anything a reader here cannot follow: table-build@8390298 is a commit in a public repository, while a run number is a line in somebody’s private log. At most 100 characters, so about 50 are left after the generator; the author is still the person whose key it was |
| X-Edit-Message | what changed, for the history |
| X-Run-Id, X-Pipeline, X-Stage, X-Engine, X-Model, X-Effort, X-Session, X-Campaign, X-Batch, X-Machine | what ran, as a record rather than a sentence. Writes naming one X-Run-Id land on one run, so a stage that sends fifty entries is one producer and not fifty. X-Pipeline is name@major.minor+digest — table-build@2.7+9f3ac1d2 — where the digest covers the files that pipeline declares in agents/pipelines/; a label carrying one is taken as written by a runner that knows what it ran, and one without as a claim typed by hand. An interactive session (Claude Code, Codex CLI, a person’s own script) sends X-Pipeline: interactive with its engine, model and session: the author stays the account whose key it is, and the tool is disclosed beside it. The engine and model are required for content uploads as described above; the remaining fields are optional. Explicit none/none records non-AI work. This describes this edit, not the origin of every entry retained from older revisions |
| returns | 201 with the allocated tid and the first revision |
| 400 | no title, no entries, or a document that is not a table |
| 413 | over a size limit |
A new table needs a title and at least one entry. One with none is a draft, and a published draft holds a permanent T-number, appears in the listings and answers nothing. The identifier is allocated here and ignored if you send one.
Replace a table's document. PUT does the same.
| X-Base-Revision | the revision you edited from. A concurrent change is then merged where it can be and refused where it cannot, instead of silently overwritten |
|---|---|
| X-Produced-By | as above |
| 409 | a stale edit whose changes overlap, or a change to the table's parameters |
| 413 | over a size limit |
The whole document, so anything the body omits
is removed. A program that computes values wants
/entries instead: assembling a document from a title, the
parameters and the numbers would delete the definition, the comments and
the references, and the result would look perfectly ordinary.
A table's parameters cannot be changed once it is published. Every entry is identified by its parameter values, so changing them reassigns every identity at once and existing citations resolve to different numbers.
The entries alone, leaving the prose untouched. This is what a generator wants.
| X-Entries-Mode | replace (default) or upsert. Upsert merges what you send into what is stored, by identity, so sending one entry leaves the other thousand alone |
|---|---|
| X-Run-Id | names one run. Submissions carrying the same run grow a single revision instead of adding one each |
| X-Rigour | how well these digits are known, recorded on the table: exact, proven, assumed-bound, heuristic (agreement-checked) or heuristic. Anything else is refused — the value of the field is that the words mean the same on every table. The only table metadata a program may set here: everything else under Data properties is somebody's prose or, in the case of repeats, somebody's judgement about two tables, and this is a fact about the computation. Both are written by sending a whole document |
| X-Produced-By | as above |
| returns | the revision, and for an upsert how many entries were added and updated |
| 429 | another write to this table held the lock for longer than 15s. Nothing was written; send it again |
Every revision holds the complete document, so a revision per entry would be a thousand copies of the whole table. A run amends its own revision instead — which works only while that revision is still the latest, so a run that will take a while should hold a lease.
Put a filled draft into the review queue. The last step of making one with a program: create the draft, fill it, then ask for a person.
Optionally send X-Review-Token with the token obtained from
the table's metadata endpoint when it was checked. The server refuses a
stale token with 409 if the revision or any attached file changed. A malformed
token returns 400. This is a concurrency precondition, not mathematical
certification. Omitting it preserves ordinary contributor submissions.
| returns | the table number, ready_for_review,
revision and the confirmed review_token |
|---|---|
| 404 | no such table, or a draft this account did not make — a draft it may not see does not answer differently for existing |
| 409 | the table is already published, or holds no numbers yet: there is nothing to review until it does |
Offering is not publishing. The draft stays invisible and unpublished; what changes is that somebody is now being asked to read it. Publishing remains a person's act, on the site.
X-Draft: ready on
/api/tables does the same thing at
creation, which is before a generator has put anything in the table. Use
that when the document arrives complete with its numbers, and this when it
does not.
Claim a table for the length of a run, refresh the claim, or drop it.
| X-Run-Id | the run the claim belongs to, so a resumed run keeps it |
|---|---|
| X-Lease-Note | what is being done, shown to whoever is turned away |
| returns | whether it is held, and when it expires |
| 409 | somebody else holds it, with their name and its expiry |
It lasts 20 minutes and is refreshed by each submission, so a run whose entries are quicker than that needs no heartbeat. It expires because a generator that dies must not lock a table for good, and it never refuses a person editing on the site: a generator's claim is against other generators.
Report what a machine’s runs cost, and what they were. The body is the run ledger as TSV; the rows are aggregated by table, model and stage and replace what is stored, so sending the same ledger twice is not paying twice. Each row also becomes a run, which is how the work that produced no table — a screening run, a triage run, a build that declined — is recorded at all.
| X-Attribution | base64 of a two-column TSV, run stamp and table, for runs whose own row never said what they were about |
|---|---|
| X-Machine | which machine the ledger came from. Two machines ran campaigns with separate ledgers and the run stamp does not say which |
| ?dry=1 | report what would change and write nothing |
| returns | how many rows, tables and runs it touched, and what it could not attribute |
| 403 | the key may write numbers but may not report costs: that is for the accounts that run campaigns, and the board |
Attach a file — usually the code that produced the numbers. The body is the file.
| X-Run-Id | carrying the run of the entries puts the file on the same revision as them |
|---|---|
| X-Rigour | how well these digits are known, recorded on the table: exact, proven, assumed-bound, heuristic (agreement-checked) or heuristic. Anything else is refused — the value of the field is that the words mean the same on every table. The only table metadata a program may set here: everything else under Data properties is somebody's prose or, in the case of repeats, somebody's judgement about two tables, and this is a fact about the computation. Both are written by sending a whole document |
| 400 | a name with a directory in it, a hidden name, or no body |
| 413 | over 2048 KB, or over 8192 KB for the table's files together |
A table's files are flat: no directories, so there is one place to look and no question about where a path leads. They are recorded, never executed.
$ curl -X POST https://numberdb.org/api/table/14/entries \
-H "Authorization: Bearer $NUMBERDB_API_KEY" \
-H "X-Entries-Mode: upsert" -H "X-Run-Id: zeta-2026-08" \
--data-binary @entries.yaml
{"tid": "T14", "url": "Values_of_the_Riemann_zeta_function_at_rational_numbers",
"revision": "9f2c...", "unchanged": false, "amended": true,
"entries": 1000, "added": 1, "updated": 0, "reviewed": true}
Every refusal carries an error saying what is wrong and, where
there is more to say, a detail saying what to do about it.