# SatelliteIndex API — /api/v1

Base URL: `https://www.satelliteindex.io/api/v1` (OpenAPI: `/api/v1/docs`, `/api/v1/openapi.json`). Envelope `{ "data": …, "meta": { request_id, generated_at, … } }`;
lists `{ "data": [], "pagination": { page, page_size, total, pages }, "meta": {} }`. Errors `{ "error": { title, detail, status }, "meta": {} }`. All times UTC ISO 8601; km, km/s, degrees, minutes.

| Endpoint | Purpose |
|---|---|
| `GET /health`, `/ready` | service + data freshness |
| `GET /satellites` | list/filter (`status, object_type, orbit_class, mission_type, country, operator, constellation, launch, launch_site, on_orbit, has_gp, launched_after/before, decayed_after, min/max_perigee, tag, q, sort, page, page_size`) |
| `GET /satellites/facets` | facet counts for the same filters |
| `GET /satellites/{slug|norad|id}` | detail: orbital_state, live position, aliases, tags, identifiers, history, memberships, provenance, events, quality flags, siblings, related, sources, freshness |
| `GET /satellites/{id}/orbit` | element-set history (append-only) |
| `GET /satellites/{id}/position?time=` | SGP4 position (lat, lon, altitude_km, velocity_km_s, source_epoch) |
| `GET /satellites/{id}/track?before=45&after=90&step=60` | ground track |
| `GET /satellites/{id}/history` | change log + daily altitude series |
| `GET /satellites/{id}/live` | position from the shared in-memory propagator |
| `GET /orbit/positions?step=30` | compact batch for the globe: `norad[]`, `cls[]`, `mission[]`, `active[]`, `pos[]` (lat0,lon0,alt0,lat1,lon1,alt1 …), `vel[]` |
| `GET /orbit/density` | altitude buckets, LEO 25 km profile, inclination profile |
| `GET /search?q=&limit=&types=` · `/search/suggest?q=` | unified search (satellites, operators, constellations, countries, launches, sites) |
| `GET /stats` · `/stats/home` | global statistics snapshot (hourly) |
| `GET /rankings?metric=constellations|operators|countries|countries-debris|launches|fastest-growing|congested-shells|launch-years` | rankings |
| `GET /constellations` · `/constellations/{slug}` | constellations + deployment analytics |
| `GET /operators` · `/operators/{slug}` | organizations |
| `GET /countries` · `/countries/{code|slug}` | countries |
| `GET /launches` · `/launches/timeline` · `/launches/{cospar}` | launches (derived from international designators) |
| `GET /launch-sites` · `/launch-sites/{slug}` | launch sites |
| `GET /debris` · `/reentries` | debris explorer · decays + low-perigee watch (not a prediction) |
| `GET /events` · `/events/{id}` | derived event feed |
| `GET /sources` · `/sources/status` · `/methodology` | transparency |
| `POST /views` | anonymous page-view beacon `{entity_type, entity_id}` |
| `/admin/*` | token-protected (`x-si-admin-token`) |

Rate limits per IP per minute: default 600, search 120, positions 60, position/track 240, admin 120.
Attribution: orbital data courtesy of CelesTrak. Not for operational use.