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

  • Career readings come back in the reader's language. Career affinity takes ?locale= — en, ru, es, pt-BR.

    • Translated: cluster, sub-cluster, profession and success-kind titles; the cluster and success-kind paragraphs; a road's source, through and manner.
    • Scores never change with the locale. Translation is applied to a finished profile, so two languages are provably the same reading with different words.
    • Not translated, on purpose: every identifier, and the sub-cluster and profession rationale (they fall back to English).
    • A language we do not carry is answered in English rather than refused; the new top-level locale field says which you received.
    • New fields on success.routes[]: source_id and element, the stable keys to branch on now that source and manner move with the locale.

  • The profession shortlist spans several areas of work. Professions inside one sub-cluster score almost identically, so the head of the ranking came back as one answer printed fifteen times — painter, plasterer, spray painter. The returned list is now capped at two per sub-cluster, which on a real chart takes the same fifteen slots from 5 distinct areas to 10. The ranking itself is unchanged, the list is still strictly strongest-first, and professions=500 still returns all 436.

  • Documented: two endpoint groups that were live but missing from these docs. No API change — the endpoints already existed.

  • Livelihood indicators — a second, classical way of reading work. New page: Livelihood indicators.

    • New GET /v1/vedic/charts/{id}/livelihood — Saturn as the significator of livelihood, and the planets casting argala on him as the decisive influences on the kind of work. Each influence reports its house, its role (sustenance / driver / catalyst / contributor), whether the planet is dignified, how far it has advanced through its sign, and which planets obstruct it.
    • Obstruction is reported, not applied: the sources state the rule and then publish readings that ignore it, so both are available and dominant considers only unobstructed influences.
    • Handles the reversed count when Ketu shares Saturn's sign — about 7.6% of charts.
    • Calibrated, and negative. Against 15,921 register-sourced births none of ten pre-registered predictions survives an era-stratified permutation test (family-wise p = 0.42). The page carries the figures. A traditional reading, never advice.

  • Career affinity: spheres of work and professions, scored from the chart. New page: Career affinity.

    • New GET /v1/charts/{id}/profile/career — 14 clusters and 72 sub-clusters of the National Career Clusters Framework (Advance CTE, 2024) and all 436 ISCO-08 unit groups, each scored 0–100 for the chart and returned strongest first, with the three parts of the score, the planets that actually carried it, and a written rationale for why those planets, signs and houses belong to that field.
    • Deterministic: no LLM, no clock, no randomness. The same chart always returns the same answer, and method_version / taxonomy_version say what produced it.
    • The response also carries a planet voice per body — its career placement, its Shadbala ratio, its Theo disposition, and the reasons it speaks about this person's work at all. capability is null for the nodes, and for every planet when the birth place has no sunrise.
    • professions (0–500, default 25) trims the profession list; professions_total always reports the full count.
    • Each of the 436 professions carries its own reading rather than inheriting its sub-cluster's, so the profession list ranks jobs against each other instead of listing one sphere's contents alphabetically.
    • Calibrated, and the result is negative. Against 15,921 register-sourced births labelled with their real professions, the endpoint does not predict occupation (AUC 0.497 against 0.500 for a coin). The endpoint page carries the figures. Treat the output as a traditional reading, never as advice or a hiring signal.

  • Theo: planet strength and disposition, as two separate answers. New page: Theo: planet strength & disposition.

    • New GET /v1/vedic/charts/{id}/theo/planets — Shadbala against the BPHS requirement per planet (ratio, where 1.0 is "classically able", plus the six components and a rank), and how benefic the planet is for this ascendant (score in −1…+1, a plain-words band, and the five weighted voices with their reasons). The nodes carry a disposition and strength: null — they have no classical requirement, and a zero would rank them last in every chart.
    • New GET /v1/vedic/charts/{id}/theo/houses — each house's share of the chart's power (the twelve sum to 1.0) and its support in −1…+1.
    • Shadbala is complete. Chesta bala and the rest of sthana (saptavargaja, ojayugma, kendradi, drekkana) are now computed, and /theo/planets reads sunrise and sunset off the birth data so the three daylight sub-balas of kala count too. GET /shadbala returns them all and simplified is now false. Before this, the composed total was short by two balas and every planet in every chart scored about 0.42 of its requirement.
    • Breaking: net_strength is gone from /influence-network, and net_strength, benefic_strength and malefic_strength are gone from /theo/sign-influences. Those numbers signed each tie by a static benefic/malefic table; because a planet does not influence itself and the table holds four benefics against five malefics, the four natural benefics scored worst in 82% of charts by arithmetic alone. Connection is now published unsigned (connection, influence_received, influence_given) with the judgement in a separate support or disposition field. See the migration table.
    • /theo/planets and /theo/houses carry method_version, currently theo-strength-disposition-v2. Pin it if your copy depends on the exact numbers.

  • 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