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://v3.factordb.com/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), and parentheses.

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

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

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 }

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

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

→ the ordered chain of certificates

cert_stats

Certificate totals.

No parameters.

→ { total, verified, pending, processing }

get_sequence

The terms of an aliquot sequence.

→ the sequence terms from from onward

sequence_sizes

Digit size of each term (data for the growth graph).

→ digit-count per iteration

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.

→ a page of sequences

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 }

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.

→ a page of numbers of that type

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

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: term or decimal)

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

health

Liveness check.

No parameters.

→ { ok: true }