Documentation

Public API

Read-only access to live catalog state, records, near-escape candidates, integrity summaries, and exportable samples.

These endpoints expose computational catalog data from the running engine. They do not constitute a proof of the Collatz Conjecture.

Back to dashboard Read methodology

Export Samples

Limited JSON and CSV exports are capped for public access.

Endpoint

/api/collatz/state

Open

Purpose

Returns the current public engine state and latest verified catalog boundary.

Query Parameters

None.

Limits

Read-only status endpoint. No catalog rows are returned.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/state

Example Response Shape

{
  "ok": "boolean",
  "generatedAt": "ISO timestamp",
  "status": "engine status",
  "numbersCataloged": "number",
  "highestVerifiedN": "number",
  "currentlyAnalyzingN": "number",
  "lastVerifiedBatch": { "start": "number", "end": "number", "size": "number" },
  "nextBatchQueued": { "start": "number", "end": "number", "size": "number" },
  "throughput": { "numbersPerSecond": "number", "lastBatchDurationMs": "number" },
  "heartbeatAgeSeconds": "number",
  "runtimeSeconds": "number"
}

Useful for dashboards, monitors, and public status displays.

Endpoint

/api/collatz/health

Open

Purpose

Returns public operating health for the autonomous engine and latest full integrity run.

Query Parameters

None.

Limits

Public-safe operational status only. No secrets, stack traces, or infrastructure details.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/health

Example Response Shape

{
  "ok": "boolean",
  "status": "health status",
  "heartbeatAgeSeconds": "number",
  "numbersCataloged": "number",
  "currentStatus": "engine status",
  "numbersPerSecond": "number",
  "lastRunAt": "ISO timestamp or null",
  "lastFullIntegrityRun": { "status": "status", "checkedAt": "ISO timestamp" },
  "message": "public status message"
}

Useful for external status displays and lightweight uptime checks.

Endpoint

/api/collatz/latest?limit=10

Open

Purpose

Returns the latest verified catalog results, ordered from newest verified n downward.

Query Parameters

limit: optional positive integer, capped at 100. Defaults to 25.

Limits

Returns a bounded result set only.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/latest?limit=10

Example Response Shape

{
  "ok": "boolean",
  "generatedAt": "ISO timestamp",
  "highestVerifiedN": "number",
  "limit": "number",
  "count": "number",
  "data": [
    {
      "n": "number",
      "steps_to_one": "number",
      "highest_peak": "number",
      "peak_ratio": "number",
      "reached_one": "boolean",
      "cataloged_at": "ISO timestamp"
    }
  ]
}

Values are computational catalog records. They do not constitute a proof.

Endpoint

/api/collatz/records

Open

Purpose

Returns current public record holders for trajectory length, highest peak, and peak ratio.

Query Parameters

None.

Limits

Peak-ratio record is computed from a bounded high-peak catalog sample.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/records

Example Response Shape

{
  "ok": "boolean",
  "generatedAt": "ISO timestamp",
  "catalogSize": "number",
  "highestVerifiedN": "number",
  "longestTrajectoryRecord": { "n": "number", "steps_to_one": "number" },
  "highestPeakRecord": { "n": "number", "highest_peak": "number" },
  "highestPeakRatioRecord": { "n": "number", "peak_ratio": "number" },
  "highestPeakRatioRecordScope": "computed from the highest-peak catalog sample"
}

Record objects use the same public result shape as latest and export endpoints.

Endpoint

/api/collatz/near-escapes?limit=10&sort=peak_ratio

Open

Purpose

Returns high-interest candidates ranked by peak ratio, steps, peak, or n.

Query Parameters

limit: optional positive integer, capped at 100. sort: peak_ratio, steps, peak, or n.

Limits

For peak_ratio sorting, ranking is derived from a bounded high-peak sample.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/near-escapes?limit=10&sort=peak_ratio

Example Response Shape

{
  "ok": "boolean",
  "generatedAt": "ISO timestamp",
  "highestVerifiedN": "number",
  "limit": "number",
  "sort": "peak_ratio",
  "count": "number",
  "data": [
    {
      "n": "number",
      "steps_to_one": "number",
      "highest_peak": "number",
      "peak_ratio": "number",
      "reached_one": "boolean",
      "flags": ["high_peak_ratio", "long_path"]
    }
  ],
  "scope": "ranked from the highest-peak catalog sample"
}

Near-escape is a public dashboard label for notable trajectories, not a mathematical exception.

Endpoint

/api/collatz/integrity

Open

Purpose

Returns a bounded live integrity summary for the public dashboard.

Query Parameters

None.

Limits

The public endpoint checks a recent bounded range for performance.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/integrity

Example Response Shape

{
  "ok": "boolean",
  "checkedAt": "ISO timestamp",
  "scope": "latest_range",
  "scopeSize": "number",
  "highestVerifiedN": "number",
  "numbersCataloged": "number",
  "checks": {
    "duplicates": { "ok": "boolean", "count": "number", "sample": [] },
    "missingRanges": { "ok": "boolean", "count": "number", "sample": [] },
    "stateMatchesCatalog": { "ok": "boolean" },
    "heartbeat": { "ok": "boolean", "ageSeconds": "number" },
    "statusReadable": { "ok": "boolean", "status": "engine status" }
  }
}

For full catalog verification, use the integrity endpoint documented in the Methodology page.

Endpoint

/api/collatz/integrity/latest

Open

Purpose

Returns the latest persisted full catalog verification summary.

Query Parameters

None.

Limits

Returns summary fields only; detailed internal logs are not exposed.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/integrity/latest

Example Response Shape

{
  "ok": "boolean",
  "latest": {
    "status": "passed, failed, or warning",
    "checkedAt": "ISO timestamp",
    "highestVerifiedN": "number",
    "numbersCataloged": "number",
    "checksPassed": "number",
    "checksFailed": "number",
    "durationMs": "number",
    "duplicateCount": "number",
    "missingRangeCount": "number",
    "stateMatchesCatalog": "boolean",
    "recordsMatchCatalog": "boolean",
    "heartbeatRecent": "boolean"
  }
}

If no full verification is recorded yet, the endpoint returns ok=false with a public-safe message.

Endpoint

/api/collatz/export?format=json&limit=10

Open

Purpose

Returns an exportable JSON sample from the verified public catalog.

Query Parameters

format: json. limit: optional positive integer, capped at 10000. offset: optional non-negative integer. order: asc or desc.

Limits

Exports are capped samples, not unlimited full-catalog dumps.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/export?format=json&limit=10

Example Response Shape

{
  "ok": "boolean",
  "generatedAt": "ISO timestamp",
  "highestVerifiedN": "number",
  "limit": "number",
  "offset": "number",
  "order": "desc",
  "count": "number",
  "data": [{ "n": "number", "steps_to_one": "number" }]
}

Use this for small public analysis samples and reproducible examples.

Endpoint

/api/collatz/export?format=csv&limit=10

Open

Purpose

Returns an exportable CSV sample from the verified public catalog.

Query Parameters

format: csv. limit: optional positive integer, capped at 10000. offset: optional non-negative integer. order: asc or desc.

Limits

Exports are capped samples, not unlimited full-catalog dumps.

Access

Public read-only access. Do not send secrets or private data to these endpoints.

Example Request

GET /api/collatz/export?format=csv&limit=10

Example Response Shape

n,steps_to_one,highest_peak,peak_ratio,reached_one,cataloged_at

CSV responses are returned as downloadable public catalog samples.