Charts

A natal chart is the foundational artifact — every other endpoint references one by id.

If the user enters a birth place by name, call GET /v1/geolocation/places first and use the selected candidate's latitude, longitude, and IANA timezone when collecting the final birth moment.

Create — POST /v1/charts

Required scope: charts:write

Request

{
    "birth": {
        "moment": "1984-12-21T18:16:00+07:00",
        "latitude": 55.0084,
        "longitude": 82.9357
    },
    "system": "western",
    "house_system": "placidus",
    "ayanamsha": null
}

Field	Type	Required	Notes
birth.moment	ISO 8601 with offset	yes	Tropical / sidereal both honour timezone. Don't pass naive datetimes.
birth.latitude	float, -90…90	yes	Decimal degrees, North positive.
birth.longitude	float, -180…180	yes	Decimal degrees, East positive.
system	"vedic" | "western"	no, default "vedic"	Selects tropical (western) vs. sidereal (vedic).
house_system	"placidus" | "whole_sign" | "equal"	no, default "placidus"	Whole-sign is recommended for Vedic.
ayanamsha	"lahiri" | null	no, default "lahiri"	Pass null to suppress for Western charts. Required for Vedic.

Response — 201 Created

Abridged:

{
    "id": "019e32b5-99da-71e3-a198-1fcea798e912",
    "system": "western",
    "ayanamsha": null,
    "house_system": "placidus",
    "computed_at": "2026-05-16T21:28:45.199836Z",
    "birth": {
        "moment": "1984-12-21T18:16:00+07:00",
        "latitude": 55.0084,
        "longitude": 82.9357
    },
    "planets": [
        {
            "planet": "sun",
            "sign": "sagittarius",
            "longitude": 269.7829,
            "degree_in_sign": 29.7829,
            "speed_per_day": 1.0149,
            "is_retrograde": false
        }
        /* ... 13 more entries: moon, mercury, venus, mars, jupiter, saturn,
              uranus, neptune, pluto, rahu, ketu, ascendant, midheaven */
    ],
    "houses": [
        { "house": 1, "sign": "cancer", "longitude": 106.7847 }
        /* ... 11 more cusps */
    ]
}

Planet keys

sun · moon · mercury · venus · mars · jupiter · saturn · uranus · neptune · pluto · rahu · ketu · ascendant · midheaven

rahu and ketu are the lunar nodes (mean nodes). ascendant and midheaven are reported as pseudo-planets so the response shape stays uniform.

Sign values

aries · taurus · gemini · cancer · leo · virgo · libra · scorpio · sagittarius · capricorn · aquarius · pisces

Vedic planet fields

When the chart is computed with system="vedic", each planet carries six additional sidereal fields (the nakshatra / navamsa enrichment). On a Western (system="western") chart these are omitted (null).

{
    "planet": "moon",
    "sign": "taurus",
    "longitude": 42.9183,
    "degree_in_sign": 12.9183,
    "speed_per_day": 13.1764,
    "is_retrograde": false,
    "nakshatra": "rohini",
    "pada": 3,
    "global_pada": 19,
    "nakshatra_lord": "moon",
    "navamsa_sign": "virgo",
    "navamsa_lord": "mercury"
}

Field	Type	Notes
nakshatra	string | null	The lunar mansion the planet sits in (one of the 27).
pada	int (1–4) | null	Quarter of the nakshatra (the navamsa division within it).
global_pada	int (1–108) | null	The pada counted across the whole zodiac (27 × 4).
nakshatra_lord	string | null	Ruling planet of the nakshatra (a planet key, e.g. "moon").
navamsa_sign	string | null	The planet's sign in the navamsa (D9) divisional chart.
navamsa_lord	string | null	Ruler of that navamsa sign (a planet key).

For the full set of Vedic divisional charts, dignities, dashas, and strengths keyed off this chart, see the Vedic endpoints.

Determinism

A chart is fully determined by (moment, lat, lon, system, house_system, ayanamsha). Identical input yields identical output; the API caches charts by content hash so repeated calls are essentially free.

Demo — POST /v1/demo/charts

Public, no auth — the endpoint behind the birth-chart widget on astrolinkers.com. Same request body as POST /v1/charts, and the same response minus the id: the chart is computed and returned but never persisted, so there is nothing to fetch later. The planet objects carry only the base six fields (no Vedic nakshatra/navamsa enrichment).

• Rate limit: per-IP (default 5 / hour); exceeding it returns 429 with reason: "demo_rate_limit_exceeded".
• Response: 200 OK, shape identical to the create response without id.

Use the authenticated POST /v1/charts for anything you need to keep or reference from other endpoints.

Fetch — GET /v1/charts/{chart_id}

Required scope: charts:read

Returns the same shape as the create response. 404 not_found if the id does not belong to the caller's tenant.

Talent profile — GET /v1/charts/{chart_id}/profile/talent

Required scope: charts:read

See Talent profile for the full schema; the short version:

{
    "chart_id": "019e32b5-...",
    "scores": [
        {
            "skill_id": "sales_negotiation",
            "value": 0.50,
            "contributing_rules": ["mercury_in_fire_sales", "venus_in_air_sales"]
        }
        /* 11 more skills */
    ]
}

value is in [0, 1]; contributing_rules is the list of rule ids that fired on this chart for this skill. The mapping (rule_id → description) is part of the public ontology and stable across releases.