All calls are JSON-RPC 2.0 sent as an HTTP POST to /rpc. The body is a request object (or an array of them for a batch); the response mirrors it.

curl -s https://factordb.com:4059/rpc \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_number","params":{"target":{"expr":"2^131-1"},"detail":2}}'

Response: {"jsonrpc":"2.0","id":1,"result":{…}}, or {…,"error":{"code","message"}} on failure.

Command-line client

fdb wraps every method on this page as a subcommand — numbers and factors, proofs, certificates, sequences, statistics, downloads and your account — with human-readable output by default and the raw JSON result on request. It can also drive an aliquot sequence forward with local gmp-ecm, reporting the factors it finds (fdb seq advance).

fdb number 2^127-1 --full
fdb report 1427247692705959880439315947500961989719490561 2^61-1
fdb download C 60 --count 100 --random

Source: github.com/mtvb/factordb-cli (Rust, GPL-2.0; cargo install --path . builds the fdb binary).

Addressing (the target parameter)

Many calls take a target, which is either an id or an expression: {"id": 42}  or  {"expr": "10^80+7"}. Expressions accept + - * / ^ %, ! (factorial), #/## (primorial), I(n)/lucas(n), the shortcuts M/F and b,n+/b,n-, named functions such as Q(n) (Perrin), @(n) (the n-th prime) and others, a reference to a stored id #<id>, and parentheses. See the full expression syntax & functions reference.

Authentication

Anonymous access works for reads within the default limits. To act as your account - higher limits, certificate upload - send your API token:

X-Fdb-User-Token: <your token>

Get a token from login / register (or rotate it with regenerate_token).

Batching

POST an array of request objects to run several calls in one round-trip; the response is an array of results in the same order, each matched by id. Calls in a batch run sequentially.

Limits & accounting

Every response carries a X-Fdb-Resources: ids=…, time_ms=…, bytes=…, bg_ms=… header summing what the request consumed. Requests are rate-limited and quota-bounded per client (ids created, wall time, bandwidth, background-check time); exceeding a budget returns HTTP 429. See Limits and call quota_status for your current usage.

write calls modify the database; account calls manage your session. Everything else is read-only.

get_idwrite

Resolve an expression to a factordb id (optionally storing it).

→ { id, status, digits, created, url }

get_number

Full record for a number: identity, status, size, and (with detail) factors, primality and sequence membership.

→ { id, status, digits, term, preview, decimal?, fully_factored, perfect_power, factors?, primality?, algebraic?, sequence_of? }

get_factors

The known factorization of a number.

→ { id, status, fully_factored, factors: [ { base, exponent, status } ] }

factor_of

The numbers a given number is a direct factor of (its cofactor "parents", one level up) - for climbing the divisor chain, e.g. to a parent with a missing algebraic factorization. Bounded.

→ { parents: [ { fid, digits, preview, term } ], truncated }

nearest_prime

The next prime above N, or - with below - the previous prime below it. Computed on request and returned view-only (resolved, not stored): it shows the existing record if already in the database, else an unstored view you can explicitly create. Capped at 3000 digits; the prime is a BPSW probable prime.

→ { found, number?: { id, status, digits, term, preview, decimal? } } (found is false only when there is no prime below N, i.e. N ≤ 2)

primality

Primality state of a number and any certificate metadata.

→ { status, digits, kind, base?, cert_size?, cert_digits?, cert_type?, cert_uploader? } (kind = direct / n-1 / n+1 / combined / certificate)

algebraic_factors

Algebraic factorization panel (e.g. difference/sum of powers, Aurifeuillian).

→ the algebraic decomposition of the expression, when one applies

snfs_poly

SNFS polynomials for a composite without known factor (80-400 digits) whose own term, or the term of a number it divides, has a special form: sums of powers of one base, binomials in two bases, cyclotomic and Aurifeuillian parts. Computed on request. As a file for GGNFS / yafu, msieve or CADO-NFS: /snfs.php?id=…&format=ggnfs|msieve|cado.

→ { n?, polys: [ { c: [c0..cd], y1, y0, skew, difficulty, scaled, side, e, form } ] } - best first; f = Σ c[i]·x^i, g = y1·x + y0, common root -y0/y1 mod n; scaled = difficulty plus the norm-imbalance penalty (selects sieving parameters), side = special-q side (a / r), e = Murphy E. Empty polys when there is nothing to offer

get_family

Neighbouring numbers of the same family (e.g. x^n±1) around an expression.

→ a list of family members with their ids/status

report_factorswrite

Submit one or more found factors of a number. Verified exactly (a wrong factor is rejected); promotes/creates rows as needed.

→ { id, status, created_ids, credited? }

check_factorswrite

Run the next bounded P-1 / P+1 / ECM step on a stored composite of at most 300 digits (the sequence page's "Check for factors"): level 0 P-1 to B1=50k, 1 three P+1 curves to B1=150k, 2 ten ECM curves to B1=250k, 3 (below 65 digits) forty ECM curves to B1=1M. A factor found is reported like report_factors. Runs up to 60 s; at most 4 at once server-wide.

→ { fid, digits, status, level, max_digits, step?, ran, factors? }

provewrite

Run a deterministic special-form proof (Pocklington N-1 / Morrison N+1 / combined BLS75). Small numbers inline; large ones queue for the background prover.

→ { proved, queued, method?, witness?, digits, promoted? } (method 1 = N-1, 2 = N+1, 3 = combined)

proof_progresswrite

Per-method completeness for a number and what each proof would cost/queue. May auto-create the N∓1 ids for a large PRP.

→ per-type completeness, thresholds, queued/est_ms and remaining background budget

proof_state

Poll a number’s proof state (after a large proof was queued).

→ { status, digits, queued }

proof_list

List numbers proven prime by a special-form test.

→ { proofs: [ { fid, digits, type, base, term, preview, tail } ] } (term is the formula when stored as one, else empty; preview/tail are the leading/trailing decimal digits for a "head…tail" display)

prp_testwrite

Run a BPSW probable-prime test on an untested (U) number; settles it U→PRP or U→C. Large ones queue.

→ { queued|tested, ... }

prp_test_info

Whether a number is PRP-testable and the cost a queued test would drain.

→ { testable, est_ms, will_queue, check_remaining_ms }

get_certificate

Download the stored primality certificate for a number (Primo / gmp-ECPP), if any.

→ the certificate text and its metadata

upload_certificatewrite

Upload a primality certificate for a number (PRP→P on verification).

→ { ok, ... }

cert_list

List certificates (newest/largest first), optionally only those still pending verification.

→ { certs: [ ... ] }

cert_chain

The certificate dependency chain for a number (a cert that references smaller certified primes). Large chains have thousands of steps: page them with skip/limit.

→ { fid, total, skip, chain: [ { step, tofid, digits, type, term, preview, tail } ] }

cert_stats

Certificate totals, plus the verifications in flight with their progress.

No parameters.

→ { total, verified, pending, processing, running: [ { fid, done, total, digits, started } ] }

cert_top

Certificate leaderboard by uploader: the top 100 accounts (uid 0 = anonymous), score = Σ (digits/1000)⁴ over verified certificates, plus totals over all uploaders.

→ { users: [ { uid, fullname, certs, size, score } ], totals: { rows, certs, size, score } }

cert_software_top

Certificate leaderboard by software: the programs (grouped, by score) and the top 100 software versions.

→ { programs: [ { program, versions, certs, size, score } ], versions: [ { type, program, version, certs, size, score } ], totals }

get_sequence

The terms of an aliquot sequence.

→ the sequence terms from from onward

sequence_sizes

Digit size of each term, plus the aliquot driver it sits on (data for the colour-by-driver growth graph).

→ { sizes: [int], drivers: [int] } - per-term digit count and driver code (0 none, 1 downdriver, 2-5 named, 6 even-perfect), parallel arrays

sequence_status

Status of a sequence (open / merged / cycle / terminated).

→ the sequence’s current status and frontier

sequence_view

A window/segment of a sequence for display.

→ a bounded view of the sequence

extend_sequencewrite

Compute and store more terms of a sequence.

→ the newly computed terms

list_sequences

Browse known sequences with sorting/filtering, including by aliquot driver.

→ { sequences: [ { start, digits, length, end, composite?, guide, class, driver } ] } (guide = factored guide of the frontier term, class = its stability, driver = the code above)

sequence_of

Which sequence a number belongs to.

→ the containing sequence’s start (if any)

status

The whole status page in one call: table counts, smallest unresolved numbers, comb-scan progress, and certificate / proof / ECM-factor stats.

No parameters.

→ a merged object; sub-sections may be null when their tables are absent

stats

Global counts per table (P / PRP / C / U / CF) and disk usage.

No parameters.

→ the count/size summary

smallest

The smallest unresolved number of each kind.

No parameters.

→ { prp, c, u }, each { fid, digits, preview, tail } (tail = trailing digits, empty when short)

comb_progress

Progress of the small-factor (comb) scanner.

No parameters.

→ per-level scan progress

digit_distribution

Row counts per digit length across a range (data for the distribution chart).

→ per-digit-length counts by table

factor_tables

Sizes of the storage tables (backs the Tables page).

No parameters.

→ row/byte sizes per table

list_by_type

List numbers of one table, smallest first.

→ { rows: [ { fid, digits, term, preview, tail } ], has_more }

prp_candidates

Probable primes ordered by how far N-1 / N+1 are factored into proven primes, most factored first - the candidates closest to a Pocklington (N-1) or Morrison (N+1) proof. Above one third a proof is possible (prove); nothing is proven without a request.

→ { rows: [ { fid, digits, term, preview, tail, nm1, np1, comb, ready } ], has_more } - nm1 / np1 / comb in hundredths of a percent (comb = the combined test, 3·max + min); ready bits: 1 = N-1 proof possible, 2 = N+1, 4 = combined

ecm_list

List factors found by ECM / P±1 (each validated by its curve group order).

→ { factors: [ { fid, digits, b1, b2, sigma, type, ts, uid, submitter, term, preview, tail } ] }

ecm_group_order

Compute the elliptic-curve group order #E(F_p) for a GMP-ECM (param, sigma) over a prime, and factor it - showing the B1 at which ECM finds p. All four parametrizations.

→ { ok, order, factors, cofactor?, largest_prime?, montgomery_a, weierstrass_a4 }

download

Pull a bounded batch of candidate numbers to work on (composites to factor, PRPs to certify, untested to test). Index-bounded and capped - light on the server.

→ { count, numbers: [ string ] } (export format: a + - * ^ term or the decimal; with terms the full stored term)

loginaccount

Authenticate; returns a session/API token to use in X-Fdb-User-Token.

→ { ok, session?, error? }

registeraccount

Create an account.

→ { ok, error? }

whoamiaccount

Identity for a session/API token.

→ { found, login, ... }

regenerate_tokenaccount

Issue a fresh API token (invalidates the old one).

→ { ok, session? }

logoutaccount

Invalidate a session/API token.

→ { ok }

quota_statusaccount

Your current resource usage against the limits (exempt from the quota block).

No parameters.

→ used vs cap for ids / wall-time / bandwidth / background-check-time

contributionsaccount

Your credited factor contributions (earned with the credit flag of report_factors), newest first. Sign-in required; an account sees only its own rows.

→ { total, largest_digits, rows: [ { fid, digits, ts, term, preview, tail, parent, parent_digits, parent_term, parent_preview, parent_tail } ] }

health

Liveness check.

No parameters.

→ { ok: true }