Skip to content

API changelog

This page tracks public-facing API changes. Internal refactors, infrastructure tweaks, and non-observable behaviour live in the repository changelog instead.

The API uses URL-path versioning. Breaking changes ship under a new prefix (e.g. /v2/...) and the previous version stays online for at least six months.

v1 — current

Unreleased

  • Vedic API expansion. New and canonicalized Vedic calculation, interpretation, relationship, and product-UX surfaces:

    • Panchanga now documents day-level, current-moment, and window-specific routes with explicit latitude, longitude, and timezone parameters.
    • Jaimini now exposes canonical /jaimini/karakas, /jaimini/arudha, /jaimini/aspects, and /dashas/chara routes while keeping the older helper routes documented for compatibility.
    • Muhurta now exposes activity taxonomy, single-candidate scoring, and window search routes in addition to the legacy chart-bound optimizer.
    • Relationships now cover Kuta matching, dosha checks, product highlights, and ranked relationship topics.
    • Risk/support/focus signals expose structured caution signals, protective signals, and date-aware focus areas.
    • Vedic interpretations and product UX add grounded natal, relationship, forecast, Muhurta prose endpoints plus frontend-ready cards for profile summaries, daily weather, next important periods, relationship highlights, and timelines.

    See Panchanga, Muhurta, Jaimini karakas and arudha, Vedic relationships, Risk, support and focus signals, Vedic interpretations, and Vedic product UX.

  • Birth-place geolocation. New GET /v1/geolocation/places endpoint resolves free-text birth places into grounded candidates with latitude, longitude, IANA time zone, population and display label. The LLM only normalizes search terms; Open-Meteo geocoding supplies the coordinates and time zone. See Geolocation.

  • Western astrology API expansion. New deterministic Western calculation surface under /v1/western/*:

    • Core calculations — aspects, essential dignities, element / modality balance, hemispheres, quadrants, house emphasis, chart patterns, lunar phase, retrograde profile, summary, house interpretations, dispositor chains, antiscia, and endpoint-level house_system overrides for Placidus / Whole Sign / Equal, plus Hermetic Lots and fixed-star contacts.
    • Predictive calculations — transit-to-natal contacts, transit windows, secondary progressions, solar arc directions, solar and lunar returns, annual profections, annual/monthly forecast summaries, progressed lunation, and level-one plus nested L1-L4 zodiacal releasing. Solar returns include return-house and return-planet overlays into natal houses for UI and LLM grounding.
    • Relationships — full synastry matrix, bidirectional house overlays, composite chart, Davison chart, Venus/Mars, Moon/Saturn, Sun/Moon and angle contacts, plus emotional / sexual / long-term / communication / conflict scores.
    • Product profiles — deterministic feature vectors for personality, career, relationship, stress, communication, leadership, money and decision-making. These are structured product/LLM inputs, not generated prose.

    See Western overview.

  • LLM-ready Western interpretations. New /v1/interpretations/natal, /v1/interpretations/relationship, and /v1/interpretations/forecast endpoints generate prose from deterministic Western grounding. Responses include grounding, features_used, and sources so generated text remains auditable. See Interpretations.

  • Western product UX endpoints. New frontend-ready card endpoints expose relationship highlights, daily personal weather, next important transit, timeline cards, profile summary cards, and ranked compatibility topics. See Western product UX.

  • Official SDKs. Python (pip install astrolinkers-sdk → import astrolinkers, v0.2.0) and TypeScript (npm install @astrolinkers/sdk-ts, v0.1.0) clients now ship as first-class integration paths. Both cover the full API surface, including streaming LLM endpoints and the Vedic engine, with typed errors, retry-aware transports, and an escape hatch for not-yet- wrapped routes. Releases are tag-triggered and publish with cryptographic build provenance (PEP 740 on PyPI, SLSA on npm). See SDKs and snippets.

  • Per-tier rate limits, response cache, usage analytics. Three features add commercial-grade controls on top of the LLM endpoints:

    • Per-tier rate limits. Independent token-bucket per tenant per tier (basic / standard / premium). Defaults sized 30/10/5 burst with 0.5 / 0.1 / 0.02 req/s sustained refill. Over-quota replies are 429 with both the Retry-After header and a body error.details.retry_after_seconds hint.
    • Response cache (24h TTL). Identical requests replay the stored row without calling the LLM — sync responses gain a cached: true flag and the streaming done event mirrors it. Pass ?fresh=true on any endpoint to bypass the cache (and refresh it).
    • Usage summary endpoint — GET /v1/llm/usage-summary?from&to[…&group_by] aggregates call_count, input_tokens, output_tokens and cost_usd over an arbitrary window, optionally grouped by interpretation_type, tier, language, or UTC day. Tenant-scoped.

    See the new Rate limits, Response cache and Usage summary sections.

  • LLM interpretations are now persisted and re-readable. Every successful /v1/llm/... call — sync or streamed — saves a row to the new llm_interpretations table with the full engine_context, generated content, language/tier, and usage (input/output tokens, latency, cost). The interpretation id is returned in the sync response body and in the streaming done event so clients can fetch the record later. Two new endpoints:

    • GET /v1/llm/interpretations — list with filters (chart_id, interpretation_type, language, tier) and pagination.
    • GET /v1/llm/interpretations/{id} — read one record.

    Re-reads do not call the LLM again, so they are free. Mid-stream failures leave no row behind. All reads are tenant-isolated. See the new Persistence section in LLM interpretations.

  • Streaming variants for every LLM endpoint. Each /v1/llm/.../stream returns a Server-Sent Event stream: a single meta event with the structured engine_context arrives first (so UIs can render grounded blocks immediately), then delta events carry token chunks as they are produced, ending in done with usage stats (input_tokens, output_tokens, latency_ms, cost_usd). Fallback within the policy chain is allowed only before the first delta — once content has flowed, the active model is locked in and any mid-stream failure surfaces as a terminal error event. Client disconnect cancels the upstream LLM call so token spend stops when the user navigates away. See the new Streaming section in LLM interpretations.

  • LLM interpretations layer. Four new endpoints producing natural-language interpretations grounded in the deterministic Vedic engine. Multilingual (English + Hindi, Tamil, Telugu, Kannada, Malayalam, Marathi, Bengali, Gujarati, Spanish) and tier-controlled (basic / standard / premium):

    • POST /v1/llm/theme/{theme} — per-life-area interpretation.
    • POST /v1/llm/chart-reading — full-chart synthesis.
    • POST /v1/llm/dasha-forecast — period-aware moment forecast.
    • POST /v1/llm/muhurta-reasoning — explain top electional candidates in a window.

    Every response includes the structured engine_context the LLM was given, so each natural-language claim is auditable back to engine math. Concrete models behind each tier are a server-side deployment decision and are never exposed in the API. See LLM interpretations.

  • Complete Vedic engine port — Phase A through E. 16 new endpoints closing the predictive + advanced layers from the original astrolink reference:

    • Phase A — Full predictive engine. 6 endpoints. Essential planets ranking per theme (133-significator catalogue), period and transit modifiers, full 7-source materialization probability with smooth-decrease coefficients, complete factor (structured explanation per theme), meta factors (cross-theme driver planets). See Predictive engine (full).
    • Phase B — Extended sambandhas. 9 sub-types beyond the base 5 — dispositor chains, navamsa-rashi cross-occupation, shared nakshatra lords. See Extended sambandhas.
    • Phase C — Full Shadbala. Three new ephemeris-time Kala sub-balas: Nathonnatha (day/night), Tribhaga (third of day/night), Ayana (solar declination). Added to the existing Shadbala page.
    • Phase D — Orb-modulated aspect strength. Continuous quadratic decay replacing binary 60-Virupa hits. Added to Aspects (Drishti).
    • Phase E1 — Ashtakavarga corrections. Trikona Shodhana + Ekadhipatya Shodhana applied to the base Bhinnashtaka. See Ashtakavarga.
    • Phase E2 — Varshaphala. Annual chart per age with Muntha and solar return. See Varshaphala.
    • Phase E3 — Alternative dashas. Yogini (8-yogini 36-year cycle) and Chara (Jaimini sign-based) alongside the existing Vimshottari. Added to Vimshottari & alternative dashas.
    • Phase E4 — Krishnamurti Paddhati. KP sub-lord lookup for any longitude (nakshatra-lord, sub-lord, sub-sub-lord). See KP sub-lord lookup.
    • Phase E5 — Muhurta optimizer. Electional moment ranker by tara + day-lord. See Muhurta optimizer.

  • Date-bound materialization probability. New endpoint GET /v1/vedic/charts/{id}/predict/materialization/{area}/at?at=<iso> composes the natal base_potential with a transit modifier derived from transit contacts landing on the area's karakas and first-house lord. Multiplier band [0.8, 1.5]. Returns the final 0..1 probability + the list of contributing contacts.

  • Vedic engine wired into talent profile. The skill ontology can now reference Phase 6-11 metrics directly via dotted paths under the vedic.* prefix (corrected planet nature, composite strength, detected yogas, house quality, sambandha totals, materialization potentials). New rules in skill_ontology.yaml use them: corrected Mercury → communication, Pancha-Mahapurusha → leadership, Dhana → sales / negotiation, bright Moon → empathy, Grahan Mrityu damps resilience. Tropical charts skip the Vedic-only paths.

  • Vedic engine — Phase 6-11 surface complete. 23 new endpoints closing the analytical / strength / predictive layers ported from the original astrolink engine. Phase breakdown:

    • Phase 6 — Analytics. Sambandhas (parivartana, conjunction, dispositor-aspect, mutual nakshatra), ten house-planet relation types, three additional yogas (Dhana, Viprit Raja, Grahan Mrityu), the D22 / D64 special vargas, and the Mercury contamination + Moon phase corrections. See Sambandhas, House-planet relations, Special vargas, Planet nature, and the updated Yogas.
    • Phase 7 — Composite strength. Vimshopaka bala across four varga groups, Varga-Dignity combinations (Parijatamsa..Vaiseshikamsa), and composite strength scoring per planet, sign, and house. See Composite strength.
    • Phase 8 — Detailed Shadbala. Partial Kala bala (paksha + vara + abda + masa + yuddha), per-house Bhava bala, and Ishta / Kashta phala. See the additions in Shadbala.
    • Phase 9 — Theo system. House role classification (KENDRA / TRIKONA / DUSTHANA + multipliers), per-sign net influence, and thematic life-area mapping. See Theo system.
    • Phase 10 — Predictive engine. House quality assessment (very-difficult..very-good) and natal "base potential" for any thematic life area. See Predictive engine.
    • Phase 11 — Transit overlay. Transit chart computed against the natal at any future moment, transit-vs-natal aspect / conjunction contacts, and Navamsa transit activations. See Transit overlay.

  • Customer-managed API keys. New scope keys:manage, three endpoints (POST /v1/api-keys, GET /v1/api-keys, POST /v1/api-keys/{id}/revoke) and a parallel verifier path so the same bearer header now accepts both JWTs and opaque ak_live_… tokens. Keys are stored as argon2id hashes; the plaintext is returned exactly once at issuance. See API keys for the full surface and Authentication for the dual-format dispatch.

2026-05 — initial v1 surface

The first publicly-stable surface of the API. Includes:

  • POST /v1/charts — natal chart creation (Western tropical and Vedic sidereal with the Lahiri ayanamsha; Placidus / whole-sign / equal house systems).
  • GET /v1/charts/{id} — fetch.
  • GET /v1/charts/{id}/profile/talent — twelve-skill rule-based profile with explainable rule activations.
  • POST /v1/interpretations — template-driven statements per skill, with optional LLM rewrite by tone.
  • GET /v1/interpretations/{id} — fetch.
  • POST /v1/reports — async PDF generation through the worker pipeline.
  • GET /v1/reports/{id} — poll status / fetch signed URL.
  • POST /v1/compatibility — synastry + Ashtakoota in a single call.
  • GET /v1/compatibility/{id} — fetch.
  • POST /v1/feedback — per-statement accuracy ratings.
  • GET /v1/feedback/{id} — fetch.
  • GET /v1/feedback/templates/{template_id} — rolling template-accuracy aggregate per tenant.

Cross-cutting:

  • JWT bearer auth (RS256 / ES256 / EdDSA) with JWKS or static-PEM key resolution.
  • OAuth-style scopes — see Authentication.
  • Uniform error envelope — see Errors.
  • Per-tenant request rate limiting and rolling LLM cost cap — see Rate limits.
  • Idempotency-Key header on every mutating endpoint.
  • X-Request-Id correlation header echoed end-to-end.

Deprecation policy

When a v1 surface is slated for removal:

  1. The endpoint or field is marked deprecated in this changelog at least six months before removal.
  2. Every response carries a Deprecation: <date> header per RFC 8594.
  3. The full removal ships under /v2/... and v1 stays online for a parallel six-month window.

No removals are currently scheduled.

Subscribe