Public API v1

Read-only access to TeraPrimes files and validated segments. Production uses protocol version 11 and format v4: a raw 23# coprime-reduction bitmap (two 23# blocks per segment), gzip-compressed without an additional mask. Responses use JSON and include server processing time.

Range convention

Range endpoints use the half-open interval [start,end). The value at start is included; the value at end is excluded. Large integer values are returned as JSON strings.

Response format

{
  "ok": true,
  "data": { "primeCount": "70435" },
  "error": null,
  "meta": {
    "requestId": "…",
    "apiVersion": "1",
    "processingMs": 4.82,
    "cacheHit": false
  }
}

Endpoints

GETStatus

/api/v1/status.php

Active goal, verified frontier, segment statuses, cumulative prime counts, storage sizes and format versions.

GETFiles

/api/v1/files.php?page=1&limit=20

Paginated public ZIP files. Each file groups up to 100 consecutive validated segments.

GETFile information

/api/v1/file.php?number=0

Segment range, counts, ZIP metadata once generated, current cache presence, and the download URL for one file.

GETSegments

/api/v1/segments.php?page=1&limit=20

Paginated internal segments. Segments remain the units used by precise API queries.

GETSegment information

/api/v1/segment.php?number=0

Range, counts, gzip checksum and validation metadata for one segment.

GETπ(N)

/api/v1/pi.php?n=1000000

Exact number of primes p ≤ N, provided N is inside the continuous verified catalogue.

GETPrime count in a range

/api/v1/primes-count.php?start=1000000&end=2000000

Exact number of primes in [start,end). Complete segments use stored counts; only edge segments are decoded.

GETPrimality lookup

/api/v1/is-prime.php?n=982451653

Looks up one value in the verified 23# coprime-reduction catalogue. This is not a probabilistic primality test.

POSTBatch primality lookup

/api/v1/is-prime.php

{"numbers":[17,19,20]}

JSON body containing 1 to 100 non-negative integers. Use Content-Type: application/json.

GETNext prime

/api/v1/next-prime.php?n=1000000

Returns the smallest verified prime strictly greater than N.

GETPrevious prime

/api/v1/previous-prime.php?n=1000000

Returns the largest verified prime strictly smaller than N.

Examples

curl "https://teraprimes.org/api/v1/pi.php?n=1000000"

curl "https://teraprimes.org/api/v1/primes-count.php?start=1000000&end=2000000"

curl -X POST "https://teraprimes.org/api/v1/is-prime.php" \
  -H "Content-Type: application/json" \
  -d '{"numbers":[17,19,20]}'

Limits and caching

Endpoint class	Per second	Per minute	Per hour
Status, file and segment metadata	5	60	1,000
Primality, π(N), prime counts and prime neighbours	2	20	200

Each row uses an independent rate-limit bucket. A limit violation returns HTTP 429 and a Retry-After header. Successful GET responses provide an ETag. Status responses are cached briefly; catalogue queries are cached for five minutes. Bitmap reads use a bounded cache of recently decompressed segments; cache misses are rebuilt and verified from the validated gzip.

Errors

Errors use an HTTP status and a stable JSON code such as invalid_parameter, range_not_verified, segment_not_found, file_not_found, rate_limited or internal_error. A request never silently calculates beyond the continuous verified frontier.

Statistics and privacy

API requests are recorded for operational statistics: endpoint, HTTP method/status, processing time, response size, cache use and request date. Client addresses are transformed with a server-side HMAC before storage; raw IP addresses and response contents are not stored. Detailed records are retained for approximately 30 days.