Compatibility

Pairwise compatibility report — Western synastry (inter-aspects between the two charts' planets) plus Vedic Ashtakoota (8-kuta marriage scoring). Both are computed in one call.

Create — POST /v1/compatibility

Required scope: compatibility:write

Request

{
    "chart_a_id": "019e32b1-0f8f-7793-a6ef-8f7dcaef7d2b",
    "chart_b_id": "019e32b1-a0af-70f2-a199-4c0e10b81c4d",
    "axis": "romantic"
}

Field	Type	Required	Notes
chart_a_id	UUIDv7	yes	Must belong to the caller's tenant.
chart_b_id	UUIDv7	yes	Same tenant, and must differ from chart_a_id. The "groom" side in Vedic terminology.
axis	enum	no, default "talent"	One of talent, romantic, team. Selects the relationship lens.
include_ashtakoota	bool	no, default true	Compute the Vedic 8-kuta block.
include_synastry	bool	no, default true	Compute the Western synastry block. At least one of the two must be true.

Response — 201 Created

{
    "id": "019e32b1-f1e3-7280-ae42-92c709ad1262",
    "chart_a_id": "019e32b1-...",
    "chart_b_id": "019e32b1-...",
    "axis": "talent",
    "computed_at": "2026-05-16T21:29:43.139295Z",
    "verdict": "borderline",
    "overall_score_percent": 54.25,

    "ashtakoota": {
        "scores": [
            {
                "kuta": "varna",
                "points": 1,
                "max_points": 1,
                "reason": "Groom Varna kshatriya, bride Varna vaishya",
                "dosha": false
            }
            /* 7 more: vashya, tara, yoni, graha_maitri, gana, bhakoot, nadi */
        ],
        "total": 15,
        "flags": ["nadi_dosha"]
    },

    "synastry": {
        "inter_aspects": [
            {
                "planet_a": "midheaven",
                "planet_b": "mars",
                "aspect": "conjunction",
                "orb_degrees": 0.2322,
                "exactness": 0.971,
                "is_harmonious": true
            }
            /* up to ~60 inter-aspects */
        ],
        "overlays_a_in_b": [
            { "planet": "venus", "falls_in_house": 8 }
        ],
        "overlays_b_in_a": [
            { "planet": "saturn", "falls_in_house": 7 }
        ],
        "harmony_score": 61.5
    }
}

ashtakoota is present only when include_ashtakoota was true; synastry only when include_synastry was true.

Field reference

Field	Type	Notes
axis	string	Echoes the requested lens (talent / romantic / team).
verdict	enum	excellent | good | borderline | challenging. Single-word summary.
overall_score_percent	float	0–100. Blends Ashtakoota + synastry quality per axis.
ashtakoota.scores[].kuta	string	One of the 8 Vedic kutas.
ashtakoota.scores[].dosha	bool	True when this kuta yields a doṣa flag.
ashtakoota.flags	string[]	Flat list of named doshas raised.
synastry.inter_aspects[].aspect	string	conjunction, sextile, square, trine, opposition, quincunx.
synastry.inter_aspects[].orb_degrees	float	Distance from exact aspect in degrees.
synastry.inter_aspects[].exactness	float	1 − (orb / max_orb). Higher is more exact.
synastry.inter_aspects[].is_harmonious	bool	Whether the aspect reads as flowing (trine/sextile/…) vs. challenging.
synastry.overlays_a_in_b[]	object	A's planets in B's houses: {planet, falls_in_house}.
synastry.overlays_b_in_a[]	object	B's planets in A's houses: {planet, falls_in_house}.
synastry.harmony_score	float	Overall synastry harmony, 0–100.

Fetch — GET /v1/compatibility/{id}

Required scope: compatibility:read

Same shape as create.

The 8 kutas

Kuta	Max points	Dimension
varna	1	Spiritual / temperamental compatibility (4-tier ranking).
vashya	2	Mutual influence.
tara	3	Health and well-being via nakshatra distance.
yoni	4	Sexual / instinctive compatibility (14 yoni archetypes).
graha_maitri	5	Friendship of sign-lords.
gana	6	Temperamental classification (deva / manushya / rakshasa).
bhakoot	7	Lunar-sign distance health flags.
nadi	8	Constitutional / health compatibility — strongest individual dosha.
Total	36

Total ≥ 28 is traditionally considered very good; 18–27 acceptable; < 18 challenging. The platform normalises this into overall_score_percent together with the synastry breakdown.

Why Vedic kutas + Western synastry in one call?

The two systems weight different axes — Ashtakoota emphasises lunar nakshatra relationships, synastry emphasises angular contacts between all major bodies. Returning both lets the client pick whichever surface fits the audience without spinning up a second computation.