Changelog

This changelog records public contract changes only: endpoints, request and response schemas, error codes, and the calculation contract (calc_version). Newest first.

Two versions move independently. The API version (0.1.0) tracks the HTTP contract — paths, schemas, status codes — while the calc_version (0.1.1) tracks numerical output, so identical input under the same calc_version returns identical digits. Both are visible at runtime: calc_version in every response’s meta and in GET /health.

July 11, 2026 — Server-Timing header

• Server-Timing: app;dur=<ms> on every /v1/* response — the server’s own processing time in milliseconds; subtract it from your observed latency to see the network’s share.
• calc_version remains 0.1.1. No served number changed.

July 10, 2026 — composite, moon, progressions, returns, and usage

• POST /v1/western/composite (2 credits) — midpoint composite chart of two subjects; positions always, houses and angles only when both subjects are located, with the composite method echoed in data.method. Composite positions omit speed, retrograde, declination, and out_of_bounds. No new error codes.
• POST /v1/western/moon (1 credit; 2 with a window) — Moon phase, sign, void-of-course, and next ingress; takes no subject and an optional datetime-only moment. A window (≤92 days) adds data.events — ingresses, void bounds, and lunations. No new error codes.
• POST /v1/western/progressions (2 credits) — secondary progressions of a natal chart to an optional target date; progressed positions always, progressed houses when subject.location is supplied. No new error codes.
• POST /v1/western/returns (2 credits) — solar or lunar return chart: the exact instant a body returns to its natal longitude, plus a full natal-style chart cast at that instant. No new error codes.
• GET /v1/usage (0 credits) — the calling key’s own current-month totals plus one daily row per day with activity.
• calc_version remains 0.1.1. These additions changed no served number.

July 9, 2026 — synastry and transits

• POST /v1/western/synastry (2 credits) — cross-chart aspects and house overlays between two natal charts; two subjects share one settings object, and each location is optional. No new error codes.
• POST /v1/western/transits (2 credits) — transiting positions and transit-to-natal aspects at one moment; takes an optional datetime-only transit block, echoed in meta.transit_resolved. The default aspect orb is a flat 3.0°, and each aspect carries a root-found exact_at.
• POST /v1/western/transits/events (3 credits) — scan a window (≤366 days) for exact transit-to-natal hits, including separate retrograde passes (pass, retrograde, orb_enter/orb_leave). The default aspect orb is a flat 1.0°.
• New setting settings.transit_bodies — the transiting body set for POST /v1/western/transits/events (default mars/jupiter/saturn/uranus/neptune/pluto/chiron; Moon and Sun opt-in), echoed in meta.settings_resolved.
• meta.request_id now appears on success responses, mirroring the field problem responses already carried.
• New error codes (all 422): transit.window.invalid, transit.window.too_large, settings.transit_bodies.empty, settings.aspects.invalid_orb.
• calc_version remains 0.1.1. These additions changed no served number.

July 8, 2026 — houses, aspects, natal, and local-time subjects

• POST /v1/western/houses (1 credit) — twelve house cusps plus angles ascendant, mc, descendant, ic, vertex, and part_of_fortune (which carries sect and formula). subject.location is required.
• POST /v1/western/aspects (1 credit) — pairwise aspect scan over the requested bodies, returning aspects and aspects_summary; location is not required.
• POST /v1/western/natal (2 credits) — composed birth chart in one call: positions (each with house), houses, flattened aspects/aspects_summary, and distributions (elements, modalities, polarities, hemispheres). subject.location is required.
• Local-time subjects — subject.local_datetime plus subject.timezone (an IANA zone) are accepted on every computation endpoint; exactly one of datetime | local_datetime is required. DST edges are enforced: an ambiguous fall-back time returns subject.time.ambiguous_local_time (with candidates), a nonexistent spring-forward time returns subject.time.nonexistent_local_time (with suggestion).
• Position gained element, modality, out_of_bounds, and house (1–12, present when subject.location is supplied); the requestable body set grew to 18, adding lilith_mean, ceres, pallas, juno, and vesta.
• New settings, all echoed in meta.settings_resolved: house_system (22 systems, default placidus), lots_formula (default sect_aware), and aspects (set of ptolemaic (default) or ptolemaic_plus_minor, plus per-type orbs).
• meta.subject_resolved gained timezone — present only on the local-time path.
• New error codes (all 422): subject.time.conflicting, subject.time.ambiguous_local_time, subject.time.nonexistent_local_time, subject.timezone.required, subject.timezone.not_applicable, subject.timezone.unknown, subject.location.required, subject.location.incomplete, settings.house_system.undefined_at_latitude.
• calc_version bumped to 0.1.1 — body speeds re-quantized from six to five decimal places for cross-architecture determinism; served speed (4 dp) may differ from 0.1.0 in the last place, and no other field changed. Re-baseline any snapshotted speed values.

July 7, 2026 — initial public surface

Early access. API version 0.1.0, calc_version 0.1.0.

• POST /v1/western/positions (1 credit) — planetary positions for a subject moment, on the shared subject and settings schemas.
• GET /health and GET /ready — unauthenticated liveness and engine-readiness probes; /health reports the Swiss Ephemeris version and current calc_version.
• Authentication — bearer API keys in a single Authorization header, with environment-identifiable prefixes ak_test_ and ak_live_.
• Errors — RFC 9457 application/problem+json on every failure, with a stable namespaced code and a per-request request_id.
• Response envelope — every success is data plus meta, where meta carries calc_version, settings_resolved, subject_resolved, and credits_charged.