Ephem · developer API · v0.1

One HTTP interface across the public space-data record.

Name: Ephem developer API
Creator: Ephem
License: https://ephem.pages.dev/terms

Every endpoint returns the same envelope. Every response is served from Cloudflare's edge with a documented cache TTL. The full OpenAPI 3.1 spec is at https://ephem-api.YOUR-SUBDOMAIN.workers.dev/openapi.json.

§1 Get a key

Free-tier keys are self-serve. One per IP per day, no email required, no dark patterns.

POST · https://ephem-api.YOUR-SUBDOMAIN.workers.dev/v1/keys

curl -sX POST https://ephem-api.YOUR-SUBDOMAIN.workers.dev/v1/keys \
  -H "content-type: application/json" \
  -d '{"label":"my laptop"}'

# → { "ok": true, "key": "ek_live_XXXXXXXX...", "tier": "free" }

The plaintext key is shown once. Ephem stores only the SHA-256 hash.

§2 Endpoints

Method	Path	Cache TTL	Purpose
GET	/v1/space-weather/kp	15 min	Latest planetary K index (NOAA/SWPC)
GET	/v1/space-weather/wind	1 min	L1 real-time solar wind (NOAA/RTSW)
GET	/v1/space-weather/mag	1 min	L1 real-time IMF magnitude and Bz (NOAA/RTSW)
GET	/v1/space-weather/xray	1 min	GOES long-band X-ray flux and flare class
GET	/v1/space-weather/proton	5 min	GOES ≥10 MeV proton flux (SEP proxy)
GET	/v1/launches/upcoming	60 min	Next launches from Launch Library 2
GET	/v1/events/recent	15 min	CME / flare / SEP events from NASA DONKI
GET	/v1/objects/{norad_id}	1 h	Orbital elements for a NORAD-catalogued object
GET	/shell/density/{alt}	24 h	Debris density in a 10 km altitude shell
GET	/shell/diff	24 h	Added / removed objects since previous propagation

§3 Example: Kp index

GET · https://ephem-api.YOUR-SUBDOMAIN.workers.dev/v1/space-weather/kp

curl -s https://ephem-api.YOUR-SUBDOMAIN.workers.dev/v1/space-weather/kp \
  -H "Authorization: Bearer ek_live_..."

{
  "source": "NOAA/SWPC",
  "fetched_at": "2026-08-04T14:00:00.000Z",
  "valid_until": "2026-08-04T14:15:00.000Z",
  "data": {
    "kp": 4.33,
    "as_of": "2026-08-04T13:59:00Z",
    "source": "NOAA/SWPC"
  }
}

Every response has the same four top-level fields. Consumers can rely on valid_until for their own caches.

§4 Pricing

Tier	Price	Req / day	Keys	Support
Free	$0	1,000	1	Community
Hobby	$29 / mo	50,000	3	Community
Pro	$199 / mo	1,000,000	10	Email · webhooks
Shell Basic	$500 / mo	10,000	5	Enterprise debris feed + monthly PDF
Shell Pro	$2,000 / mo	200,000	20	Custom shells · Slack channel
Enterprise	custom	unbounded	—	SLA · on-prem cache · dedicated

Consumer overhead map is always free — it's the distribution funnel, not a revenue line.

§5 Discipline

Ephem's design commitments:

One envelope for every response. If a new endpoint needs a different shape, the new endpoint is wrong.
No breaking changes without a versioned URL prefix (/v1, then /v2). Sunset windows are minimum six months.
Every upstream is verified weekly — see /status. When an upstream moves, your call still works.
No SDKs in the first six months. REST + OpenAPI is enough for most languages; the surface area is small enough that a bespoke client is worse than a well-typed fetch.
No AI features. No chatbot. No summarisation. The data is the product.

[ Machine-readable docs → ]