API

All endpoints return data drawn from the local archive. Live per-request CelesTrak fallback is disabled (see About), so an empty archive returns no results until an ingest has run.

GET /api/gp

Search OMM records. Returns JSON.

Parameter	Description
`start-date`, `start-time`	Range start (YYYY-MM-DD, HH:MM, UTC). Defaults to "all".
`end-date`, `end-time`	Range end. Defaults to now.
`before`, `after`	Days; include the nearest snapshot just outside the range per satellite.
`satellite-name`	Case-insensitive substring of the object name.
`norad-nr`	Exact NORAD catalog ID.
`limit`	Max records to return (default 1000).

Example

GET /api/gp?norad-nr=25544&start-date=2026-01-01&end-date=2026-06-01

Response shape

{
  "source": "archive",
  "count": 128,
  "returned": 128,
  "notes": [],
  "results": [ { "OBJECT_NAME": "ISS (ZARYA)", "NORAD_CAT_ID": 25544, "EPOCH": "...", ... } ]
}

GET /api/download

Same query parameters as /api/gp, plus format=json|csv|tle. Returns a file download of the full result set.

GET /api/download?norad-nr=25544&format=tle

GET/POST /api/ingest

Fetch current OMM from CelesTrak and store new snapshots. Optional groups=active,stations to choose CelesTrak groups, and token=... (the SATDB_INGEST_TOKEN value, required). Meant to be called on a schedule. Groups queried less than 2 hours ago are skipped (listed in skipped); if all are, it returns 429 with Retry-After. Returns 503 while CelesTrak requests are blocked (see below).

curl -X POST "http://localhost:3000/api/ingest?groups=active&token=..."

GET/POST /api/ingest/unblock

Any non-200 response from CelesTrak suspends all further CelesTrak requests. GET returns whether requests are blocked and why; POST clears the block so ingest resumes. Requires token=....

curl -X POST "http://localhost:3000/api/ingest/unblock?token=..."