API DOCS

♄ AUTHENTICATION & BILLING

/api/v1/ai-guidance, /api/v1/aspect-interpretations/expand, /api/v1/electional-spellcasting, /api/v1/month/full, /api/v1/solar-return, /api/v1/solar-return/elect-location, /api/v1/synastry, /api/v1/timeline/full, /api/v1/transits, /api/v1/vedic-chart/full, and /api/v1/natal-reading/full require a Bearer token (a signed-in browser session also works); their costs are in the route index below. Get your key from the API Keys page.

Base URL: https://electional.io. Free routes cap anonymous callers per IP and answer 429 with code: "free_tier_limit" over the cap; a valid Bearer key or signed-in session is not capped (limits are in the route index).

Developer plan checkout returns through verified checkout to /api-keys. Key creation remains explicit: checkout never creates a key or runs a chargeable API request automatically.

Authorization: Bearer sk_tr_your_key_here

/api/v1/transits: 1 credit per billable calendar month (×3 when a secondChart adds the secondary and composite scans), plus a flat 1 credit when transitToTransit: true. Predictive overlays add +1 credit each, at most +3 credits per run. Credits exposed via x-credits-remaining.

/api/v1/electional-spellcasting: 1 credit per intent per billable calendar month, multiplied by 3 when a secondChart adds the secondary and composite scans. Transit-to-transit data is always calculated, but its scoring contribution can be disabled per request or via saved account settings.

Transit and Electional ranges may extend through the same calendar date next year. Paid work is durably queued first; jobs estimated at five minutes or more always return 202. Reuse one Idempotency-Key for network retries, then poll the returned Bearer-scoped statusUrl and fetch resultUrl when complete (see Report jobs).

/api/v1/synastry: 1 credit per successful compatibility report (two charts → domain-scored synastry, house overlays, and composite evidence).

/api/v1/daily-elections: Free: 3 runs per IP per week, no auth needed. Then 1 credit per run with a Bearer key or signed-in session; memberships with unlimited Daily Elections run free. Predictive overlays add +1 credit each, at most +3 credits per run, even for members, and need auth. secondChart (joint mode) costs 2 credits and needs auth; members run it free.

/api/v1/timeline: free Timeline teaser, no Bearer token required. It accepts up to 5 optional dated events and returns proof moments, hinge years, and date-only age-cycle/profection signatures without persistence or credit billing.

/api/v1/timeline/full: paid full Timeline report, Bearer token required, 3 credits after a successful exact-time scan. It auto-saves the report for the API-key owner and keeps the free teaser separate.

/api/v1/month: free Month Ahead teaser, no Bearer token required. It returns deterministic daily intensity, peak windows, domains, and timing spine without persistence or credit billing.

/api/v1/month/full: paid full Month Ahead report, Bearer token required, 3 credits after a successful exact-time forecast. It adds the generated narrative, auto-saves the report for the API-key owner, and returns raw JSON only.

/api/v1/vedic-chart: free exact-birth Vedic Chart scored reading, no Bearer token required. It returns tropical Vedic confidence-weighted domain claims, Vimshottari timing, nakshatra, vargas, and a technical comparison drawer without persistence or credit billing.

/api/v1/vedic-chart/full: paid full Vedic Chart report, Bearer token required, 3 credits after a successful exact-time scan. It auto-saves the report for the API-key owner and returns raw JSON only.

/api/v1/natal-reading: free exact-birth Natal Reading teaser, no Bearer token required. It returns the hero answer, placements, the top three tensions, one growth lever, and the parenting block in child mode, without persistence or credit billing (anonymous callers: 20 per day).

/api/v1/natal-reading/full: paid full Natal Reading, Bearer token required, 3 creditsafter a successful exact-time reading. It adds every tension's pair-specific reading, the full aspect inventory, the full growth plan, the Vedic lens, the three-frame house table, midpoints, and a grounded narrative, auto-saves the reading for the API-key owner, and returns raw JSON only.

/api/v1/ai-guidance: a flat 3 credits per request, whether the request contains one item or many.

/api/v1/aspect-interpretations/expand: 1 credit only when a new exact aspect/sign/house/dignity blend is saved. Existing blends are returned without another charge.

COMPLETE PUBLIC ROUTE INDEX

Every public POST /api/v1 route is listed here with its auth model, credit behavior, and matching MCP tool name, followed by the two GET routes that redeem a report-job receipt. The generated endpoint reference below gives a request example, response shape, and consumer notes for every POST route.

COMPLETE ENDPOINT REFERENCE

This section is generated from the shared public API catalog used by the MCP server docs. Treat each response as a representative shape; production responses can include additional evidence fields.

{
  "domain": "election",
  "orientation": "pragmatic",
  "scope": "many",
  "items": [
    {
      "peakAtIso": "2026-07-01T16:30:00.000Z",
      "score": {
        "total": 18.4
      }
    },
    {
      "peakAtIso": "2026-07-02T18:00:00.000Z",
      "score": {
        "total": 16.9
      }
    }
  ],
  "context": {
    "intent": {
      "name": "Networking"
    }
  },
  "question": "Which window is strongest for a public launch?"
}

{
  "guidance": "Use the first window for the launch announcement; reserve the second for follow-up outreach.",
  "metadata": {
    "domain": "election",
    "orientation": "pragmatic",
    "scope": "many",
    "itemCount": 2,
    "creditsCharged": 3,
    "creditsRemaining": 7,
    "model": "glm-5.2",
    "promptTemplate": "election-pragmatic-many.md"
  }
}

{
  "context": {
    "surface": "transits",
    "relationshipType": "natal_to_transit",
    "aspect": "square",
    "aspectDomain": "zodiac",
    "exactOrb": 0.42,
    "isApplying": true,
    "subject": {
      "point": "mars",
      "role": "transiting",
      "sign": "Leo",
      "house": 11,
      "dignity": "peregrine"
    },
    "object": {
      "point": "moon",
      "role": "natal",
      "sign": "Scorpio",
      "house": 3,
      "dignity": "fall"
    }
  }
}

{
  "expansionKey": "expand|v1|transits|natal_to_transit|zodiac|transiting|mars|Leo|11|peregrine|square|natal|moon|Scorpio|3|fall",
  "created": true,
  "creditsCharged": 1,
  "creditsRemaining": 6,
  "interpretation": {
    "key": "mars-square-moon-transit",
    "title": "Mars square Moon",
    "contextLabel": "Mars in Leo H11 square natal Moon in Scorpio H3",
    "summary": "A sharp emotional activation around speech, groups, and loyalty.",
    "general": "...",
    "pairMeaning": "...",
    "chartFlavor": "...",
    "timing": "...",
    "practical": "...",
    "sourceNotes": []
  }
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "scanMode": "day",
  "browserNowIso": "2026-10-01T07:15:00.000Z",
  "browserTimezone": "Europe/London",
  "startTime": "09:00",
  "endTime": "17:00",
  "scoring": {
    "useNatalHouseFrameOnly": false
  }
}

{
  "metadata": {
    "scanMode": "day",
    "scanStartIso": "2026-07-01T13:00:00.000Z",
    "scanEndIso": "2026-07-01T21:00:59.999Z",
    "intentCount": 72,
    "creditsRemaining": null,
    "isFreeUse": true,
    "freeUsage": {
      "used": 1,
      "limit": 3,
      "remaining": 2
    }
  },
  "windows": [
    {
      "intentId": "career-advancement-promotion",
      "intentName": "Career Advancement and Promotion",
      "peakAtIso": "2026-07-01T15:20:00.000Z",
      "score": {
        "total": 18.24,
        "pass1Baseline": 3.6,
        "pass2HouseAlignment": 4.55
      },
      "moonVoidOfCourse": {
        "isVoid": false,
        "nextMoonHitAtIso": "2026-07-01T18:45:00.000Z"
      }
    }
  ]
}

{
  "intentId": "career-advancement-promotion",
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01",
  "rangeDays": 7,
  "strictness": "standard",
  "maxWindows": 3,
  "scoring": {
    "enabledPasses": [
      "pass1Baseline",
      "pass3IntentFit",
      "pass4NatalCompatibility"
    ],
    "useNatalHouseFrameOnly": false
  }
}

{
  "metadata": {
    "scanStartDate": "2026-10-01",
    "scanEndDate": "2026-10-08",
    "transitToTransitUsed": true,
    "strictness": "standard",
    "creditsRemaining": 12
  },
  "intent": {
    "id": "career-advancement-promotion",
    "house": 10,
    "polarity": "constructive"
  },
  "windows": [
    {
      "startAtIso": "2026-10-04T12:00:00.000Z",
      "peakAtIso": "2026-10-04T15:00:00.000Z",
      "endAtIso": "2026-10-04T18:00:00.000Z",
      "score": {
        "total": 18.24,
        "pass1Baseline": 3.6,
        "pass3IntentFit": 4.12
      },
      "planetConditions": [
        {
          "point": "sun",
          "score": 3.6,
          "band": "commanding",
          "house": 10
        }
      ]
    }
  ]
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-01-01",
  "endDate": "2030-12-31",
  "orbDegrees": 3
}

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "locationLabel": "London, United Kingdom",
    "startDate": "2026-01-01",
    "endDate": "2030-12-31",
    "eclipseCount": 8,
    "hitCount": 2,
    "caveats": [
      "Exact birth time and birthplace are required because ASC/MC eclipse contacts are birth-time sensitive."
    ]
  },
  "eclipses": [
    {
      "id": "solar-2026-08-12",
      "kind": "solar",
      "longitude": 140,
      "typeLabel": "Solar eclipse candidate"
    }
  ],
  "hits": [
    {
      "eclipseId": "solar-2026-08-12",
      "natalPoint": "sun",
      "aspect": "conjunction",
      "orbDegrees": 0.8
    }
  ]
}

{
  "goal": "sign a lease on a new apartment"
}

{
  "mode": "match",
  "intentIds": [
    "contract-legal-advantage"
  ],
  "confidence": 0.89,
  "available": true
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01"
}

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "fullReportAvailable": false,
    "narrativeIncluded": false
  },
  "forecast": {
    "verdict": {
      "headline": "Mixed but workable month",
      "score": 63
    },
    "dailyIntensity": [
      {
        "date": "2026-07-01",
        "score": 42,
        "eventCount": 2
      }
    ],
    "peakWindows": [],
    "domains": [],
    "timingSpine": []
  },
  "aiNarrative": null
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01",
  "days": 30
}

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_abc123",
    "fullReportAvailable": true,
    "narrativeIncluded": true
  },
  "forecast": {
    "verdict": {},
    "dailyIntensity": [],
    "peakWindows": [],
    "domains": [],
    "timingSpine": []
  },
  "aiNarrative": {
    "model": "glm-5.2",
    "provider": "zai",
    "text": "..."
  }
}

{
  "items": [
    {
      "tier": "bigthree",
      "sunSign": "Capricorn",
      "moonSign": "Leo",
      "ascSign": "Libra"
    }
  ]
}

{
  "interpretations": [
    {
      "tier": "bigthree",
      "key": "v1|bigthree|capricorn|leo|libra",
      "text": "A concise grounded interpretation for this Big Three stack."
    }
  ],
  "rateLimited": false
}

{
  "point": "venus",
  "sign": "Capricorn",
  "house": 8
}

{
  "cached": false,
  "interpretation": {
    "point": "venus",
    "sign": "capricorn",
    "house": 8,
    "text": "Grounded placement interpretation text."
  }
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-01-01",
  "endDate": "2030-12-31",
  "orbDegrees": 3
}

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "locationLabel": "London, United Kingdom",
    "startDate": "2026-01-01",
    "endDate": "2030-12-31",
    "scannedTransitCount": 42,
    "hitCount": 1,
    "caveats": [
      "Only Mercury, Venus, and Mars retrograde or station-grade contacts are personalized here."
    ]
  },
  "hits": [
    {
      "transitingPoint": "mercury",
      "natalPoint": "sun",
      "exactAtIso": "2026-02-03T00:00:00.000Z",
      "motion": {
        "isRetrograde": true,
        "relevance": "retrograde_contact"
      }
    }
  ]
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "solarReturn": {
    "enabled": true,
    "returnMode": "tropical_non_precessed",
    "locationBasis": "natal"
  }
}

{
  "metadata": {
    "locationLabel": "London, United Kingdom",
    "returnMode": "tropical_non_precessed",
    "locationBasis": "natal",
    "creditsRemaining": 8
  },
  "annualContext": {
    "profection": {
      "ageYears": 36,
      "profectionHouse": 1,
      "lordOfYear": "mercury"
    },
    "solarReturn": {
      "ascendantSignName": "Gemini",
      "ascendantRuler": "mercury"
    }
  },
  "categoryScores": [
    {
      "id": "CAREER",
      "score": {
        "total": 21.4,
        "band": "STRONG"
      }
    }
  ],
  "srTransitWindows": []
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "intentCategory": "CAREER",
  "returnMode": "tropical_non_precessed",
  "topN": 10
}

{
  "metadata": {
    "intentCategory": "CAREER",
    "candidatesEvaluated": 4400,
    "theoreticalMax": 37,
    "creditsRemaining": 7
  },
  "profection": {
    "ageYears": 36,
    "profectionHouse": 1,
    "profectedSignName": "Gemini",
    "lordOfYear": "mercury"
  },
  "candidates": [
    {
      "city": {
        "name": "Dublin",
        "country": "IE",
        "label": "Dublin, IE"
      },
      "total": 27.5,
      "percent": 74,
      "band": "PRIME",
      "components": [],
      "topCategories": [],
      "vetoed": false,
      "caveats": []
    }
  ]
}

{
  "chartA": {
    "label": "Jordan",
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK"
  },
  "chartB": {
    "label": "Riley",
    "birthDate": "1992-03-20",
    "birthTime": "08:15",
    "locationQuery": "Paris, France"
  }
}

{
  "metadata": {
    "chartALabel": "Jordan",
    "chartBLabel": "Riley",
    "chartALocationLabel": "London, United Kingdom",
    "chartBLocationLabel": "Paris, France",
    "ephemerisMode": "SWIEPH",
    "creditsRemaining": 9,
    "houseSystem": "P",
    "orbModel": "planet_class",
    "chartATimeKnown": true,
    "chartBTimeKnown": true
  },
  "relationship": {
    "chartALabel": "Jordan",
    "chartBLabel": "Riley",
    "overall": {
      "percentile": 71,
      "band": "promising",
      "headline": "Stronger than most pairings for Marriage & romance; High friction is the growth edge.",
      "strongestDomainId": "marriage_romance",
      "growthEdgeDomainId": "friction_challenges",
      "confidence": "high",
      "confidenceReasons": [
        "Exact birth times and stable bands across ±30 minutes."
      ]
    },
    "domains": [
      {
        "id": "marriage_romance",
        "label": "Marriage & romance",
        "score": 8.75,
        "maxScore": 14,
        "percent": 63,
        "percentile": 84,
        "rawScore": 9.4,
        "band": "strong",
        "evidence": [
          {
            "kind": "synastry_aspect",
            "label": "Jordan Sun trine Riley Moon (orb 1.2°)",
            "points": 4,
            "detail": "Core identity meets emotional nature — the classic marriage signature."
          }
        ],
        "caveats": [],
        "timeStability": {
          "status": "stable",
          "bandsSeen": [
            "strong"
          ],
          "windowMinutes": 30,
          "percentileRange": [
            80,
            88
          ]
        }
      }
    ],
    "topAspects": [],
    "aspectCounts": {
      "supportive": 6,
      "challenging": 3,
      "charged": 2
    }
  },
  "charts": {
    "a": {
      "points": {}
    },
    "b": {
      "points": {}
    },
    "composite": {
      "points": {}
    }
  }
}

{
  "birthDate": "1990-01-01",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    },
    {
      "id": "event-3",
      "label": "Launched project",
      "date": "2024-11-20"
    }
  ]
}

{
  "metadata": {
    "eventCount": 2,
    "birthTimeMode": "date_only",
    "creditsCharged": 0,
    "fullReportAvailable": false
  },
  "analysis": {
    "events": [
      {
        "label": "Moved cities",
        "ageDecimal": 29.567,
        "universalAgeCycles": [
          {
            "cycleId": "saturn-return-1"
          }
        ],
        "dateOnlyPlanetaryHits": [
          {
            "transitingPoint": "saturn",
            "aspect": "square",
            "natalPoint": "sun"
          }
        ]
      }
    ],
    "caveats": [
      "Date-only planetary hits use noon UTC samples."
    ]
  },
  "teaser": {
    "proofMoments": [],
    "hingeYears": []
  }
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    },
    {
      "id": "event-3",
      "label": "Launched project",
      "date": "2024-11-20"
    }
  ],
  "eventTransitWindowDays": 30,
  "lifetimeEndDate": "2026-12-31"
}

{
  "metadata": {
    "birthTimeMode": "exact",
    "eventCount": 2,
    "creditsCharged": 3,
    "creditsRemaining": 9,
    "savedItemId": "calc_timeline_123"
  },
  "analysis": {
    "natalLots": {
      "fortune": {
        "longitude": 112.4
      },
      "spirit": {
        "longitude": 288.1
      }
    },
    "eclipseHits": [],
    "eventWindows": [],
    "lifetimeTransits": []
  },
  "aiNarrative": {
    "model": "glm-5.2",
    "templateName": "timeline-narrative.md",
    "text": "..."
  }
}

{
  "items": [
    {
      "transitingPoint": "jupiter",
      "aspect": "trine",
      "natalPoint": "sun",
      "natalHouse": 10,
      "transitingSign": "Cancer",
      "natalSign": "Pisces"
    }
  ]
}

{
  "interpretations": [
    {
      "transitingPoint": "jupiter",
      "aspect": "trine",
      "natalPoint": "sun",
      "natalHouse": 10,
      "key": "v1|jupiter|trine|sun|10",
      "text": "A grounded generic interpretation for this transit pattern."
    }
  ]
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "startDate": "2026-10-01",
  "rangeDays": 14,
  "transitToTransit": true,
  "transitingPoints": [
    "jupiter",
    "saturn",
    "chiron"
  ],
  "aspects": [
    "conjunction",
    "trine",
    "opposition"
  ]
}

{
  "metadata": {
    "locationLabel": "London, United Kingdom",
    "timezone": "Europe/London",
    "ephemerisMode": "SWIEPH",
    "creditsRemaining": 4
  },
  "natal": {
    "points": {
      "sun": 280.46,
      "moon": 12.45
    }
  },
  "transits": [
    {
      "transitingPoint": "jupiter",
      "natalPoint": "sun",
      "aspect": "trine",
      "enterAtIso": "2026-10-03T00:00:00.000Z",
      "exactAtIso": "2026-10-08T14:23:00.000Z",
      "exitAtIso": "2026-10-12T00:00:00.000Z",
      "exactOrb": 0.12
    }
  ],
  "annualContext": null
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "relocationQuery": "Paris, France",
  "reportMode": "scored_reading"
}

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "fullReportAvailable": true,
    "locationLabel": "London, United Kingdom",
    "timezone": "Europe/London",
    "reportMode": "scored_reading",
    "relocationLabel": "Paris, France"
  },
  "report": {
    "metadata": {
      "version": "v1",
      "referenceDateIso": "2026-10-01T00:00:00.000Z",
      "frames": [
        "western_tropical",
        "tropical_vedic",
        "sidereal_vedic"
      ]
    },
    "summary": {
      "topSigns": {
        "tropicalBirth": [],
        "tropicalRelocated": [],
        "siderealBirth": [],
        "siderealRelocated": []
      },
      "activeDasha": {
        "label": "Venus-Saturn",
        "lords": [
          "venus",
          "saturn"
        ],
        "periods": []
      },
      "moonNakshatra": {
        "name": "Rohini",
        "pada": 2,
        "lord": "moon"
      },
      "frameStableHighlights": []
    },
    "scoredReading": {
      "domains": [],
      "timingSpine": {}
    },
    "domains": [
      {
        "id": "career",
        "label": "Career",
        "score": 78,
        "band": "active",
        "statement": "Visible public-role emphasis.",
        "evidence": []
      }
    ],
    "dasha": {
      "referenceDateIso": "2026-10-01T00:00:00.000Z"
    },
    "nakshatras": {},
    "vargas": {},
    "yogaAnalysis": {},
    "comparison": {}
  }
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "relocationQuery": "Paris, France",
  "includeVargaDeepDive": true,
  "reportMode": "scored_reading"
}

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 3,
    "creditsRemaining": 9,
    "savedItemId": "calc_vedic_123",
    "fullReportAvailable": true,
    "locationLabel": "London, United Kingdom",
    "timezone": "Europe/London",
    "reportMode": "scored_reading",
    "relocationLabel": "Paris, France"
  },
  "report": {
    "metadata": {
      "version": "v1",
      "referenceDateIso": "2026-10-01T00:00:00.000Z",
      "frames": [
        "western_tropical",
        "tropical_vedic",
        "sidereal_vedic"
      ]
    },
    "summary": {
      "topSigns": {
        "tropicalBirth": [],
        "tropicalRelocated": [],
        "siderealBirth": [],
        "siderealRelocated": []
      },
      "activeDasha": {
        "label": "Venus-Saturn",
        "lords": [
          "venus",
          "saturn"
        ],
        "periods": []
      },
      "moonNakshatra": {
        "name": "Rohini",
        "pada": 2,
        "lord": "moon"
      },
      "frameStableHighlights": []
    },
    "scoredReading": {
      "domains": [],
      "timingSpine": {}
    },
    "domains": [
      {
        "id": "career",
        "label": "Career",
        "score": 78,
        "band": "active",
        "statement": "Visible public-role emphasis.",
        "evidence": []
      }
    ],
    "dasha": {
      "referenceDateIso": "2026-10-01T00:00:00.000Z"
    },
    "nakshatras": {},
    "vargas": {},
    "yogaAnalysis": {},
    "comparison": {}
  },
  "vargaDeepDives": [
    {
      "code": "D9",
      "title": "D9 · Navamsa — the inner self, spouse, dharma",
      "sections": [
        "In the tropical navamsa the lagna lord holds its own sign, traditionally read as a steady core rather than a promise.",
        "The D9 lagna lord sits in the 1st in its own sign (D9 lagna Leo · Sun Leo 1st (own))"
      ]
    }
  ]
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "pastEvents": [
    {
      "date": "2021-03-10",
      "label": "Changed jobs"
    }
  ],
  "includePredictive": true
}

{
  "metadata": {
    "version": "v1",
    "sourceRoute": "/api/v1/vedic-chart/predictions",
    "locationLabel": "London, United Kingdom"
  },
  "domains": [
    {
      "id": "career",
      "score": 81,
      "evidence": [
        "Dasha and gochara confirmations overlap."
      ]
    }
  ],
  "predictiveWindows": [
    {
      "id": "career-2026-q3",
      "label": "Career opening",
      "score": 76
    }
  ],
  "confirmations": []
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "referenceDate": "2026-10-01",
  "houseSystem": "P",
  "subject": "self",
  "includeLilith": true
}

{
  "metadata": {
    "creditsCharged": 0,
    "fullReportAvailable": true,
    "reportMode": "teaser",
    "locationLabel": "London, United Kingdom",
    "houseSystem": "P",
    "subject": "self",
    "generatedAtIso": "2026-08-23T12:00:00.000Z"
  },
  "report": {
    "version": "natal-reading-v1",
    "mode": "self",
    "subjectLabel": "you",
    "teaser": true,
    "hero": {
      "eyebrow": "Natal reading",
      "title": "Saturn-led chart with a Sun square Saturn tension to work",
      "summary": "Structure is the strength; self-permission is the practice.",
      "signals": [
        "Saturn angular in the 10th",
        "Sun square Saturn, 1.8 degrees"
      ],
      "receipt": "Saturn ♑ 10th"
    },
    "placements": [],
    "signatures": [],
    "tensions": [],
    "gifts": [],
    "growth": [],
    "caveats": [
      "Dates and positions are astronomy; meanings are traditional astrology, not certainties."
    ]
  }
}

{
  "birthDate": "2019-03-14",
  "birthTime": "06:42",
  "locationQuery": "London, UK",
  "subjectName": "Sam",
  "referenceDate": "2026-10-01",
  "houseSystem": "P",
  "subject": "child"
}

{
  "metadata": {
    "creditsCharged": 3,
    "creditsRemaining": 7,
    "fullReportAvailable": true,
    "reportMode": "deep",
    "locationLabel": "London, United Kingdom",
    "houseSystem": "P",
    "subject": "child",
    "savedItemId": "calc_natal_123",
    "generatedAtIso": "2026-08-23T12:00:00.000Z"
  },
  "report": {
    "version": "natal-reading-v1",
    "mode": "child",
    "subjectLabel": "Sam",
    "ageBand": "7-12",
    "teaser": false,
    "hero": {
      "eyebrow": "Natal reading",
      "title": "Moon-led chart with a Moon opposition Saturn tension to support",
      "summary": "Feelings run deep and want proof of safety; steady routines help.",
      "signals": [
        "Moon angular in the 4th",
        "Moon opposition Saturn, 2.4 degrees"
      ],
      "receipt": "Moon ♋ 4th"
    },
    "placements": [],
    "signatures": [],
    "tensions": [],
    "gifts": [],
    "growth": [],
    "parenting": {
      "ageBand": "7-12",
      "voice": "Written for the adult raising this child.",
      "cautions": []
    },
    "houseFrames": {
      "table": [],
      "divergences": []
    },
    "caveats": []
  },
  "aiNarrative": {
    "text": "A grounded natal portrait anchored to the receipts above.",
    "model": "glm-5.2",
    "receipts": [
      "Moon ♋ 4th"
    ]
  }
}

{
  "birthDate": "1990-01-01",
  "birthTime": "12:00",
  "locationQuery": "London, UK",
  "houseSystem": "P"
}

{
  "metadata": {
    "creditsCharged": 0,
    "birthTimeMode": "exact",
    "locationLabel": "London, United Kingdom",
    "referenceDateIso": "2026-07-01"
  },
  "guesses": [
    {
      "kind": "past_event",
      "lifeArea": "marriage",
      "claim": "You likely formed or ended a major committed partnership around 2018.",
      "window": "2018",
      "confidence": "strong",
      "falsifiableCheck": "Did a marriage, engagement, or serious breakup happen around then?",
      "evidenceRefs": [
        "Pluto conjunction natal Venus",
        "Marriage & spouse (score 78)"
      ]
    }
  ],
  "evidence": {
    "pastWindows": [],
    "lifeDomains": [],
    "hingeYears": []
  },
  "synthesisError": null
}

{
  "domain": "election",
  "orientation": "pragmatic",
  "items": [
    {
      "intentName": "Networking",
      "peakAtIso": "2026-07-01T15:20:00.000Z",
      "score": {
        "total": 18.24
      }
    }
  ],
  "context": {
    "route": "/today"
  }
}

{
  "synthesis": {
    "headline": "Best used for outreach with a clear ask.",
    "bullets": [
      "Lead with the strongest contact window.",
      "Keep the follow-up within the same afternoon."
    ]
  }
}

POST/api/v1/month

Free Month Ahead teaser for exact birth data. No Bearer token required. It returns the deterministic forecast shell: verdict, daily intensity, peak windows, confidence-ranked domains, timing spine, flat evidence events, and provenance.

REQUEST BODY - JSON

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/month \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "startDate": "2026-10-01"
  }'

RESPONSE

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "fullReportAvailable": false,
    "narrativeIncluded": false
  },
  "forecast": {
    "verdict": {
      "headline": "Mixed but workable month",
      "summary": "Peak support clusters around mid-month.",
      "score": 63
    },
    "dailyIntensity": [
      { "date": "2026-07-01", "score": 42, "eventCount": 2 }
    ],
    "peakWindows": [],
    "domains": [],
    "timingSpine": [],
    "provenance": { "rulesetVersion": "scored-reading-v2" }
  },
  "aiNarrative": null
}

POST/api/v1/month/full

Paid full Month Ahead report for exact birth data. Bearer token required. Costs 3 credits only after payload validation and sufficient-credit checks succeed.

This route returns raw JSON only: the deterministic forecast plus the generated narrative, credit metadata, and the saved Month Ahead item id. Web-session customers use the same engine through /api/calculations/month.

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/month/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "startDate": "2026-10-01",
    "days": 30
  }'

RESPONSE

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_...",
    "fullReportAvailable": true,
    "narrativeIncluded": true
  },
  "forecast": {
    "verdict": {},
    "dailyIntensity": [],
    "peakWindows": [],
    "domains": [],
    "timingSpine": []
  },
  "aiNarrative": {
    "model": "glm-5.2",
    "provider": "zai",
    "text": "..."
  }
}

POST/api/v1/vedic-chart

Free Vedic Chart scored reading for exact birth data. No Bearer token required. The default reportMode is scored_reading: tropical Vedic domain claims with deterministic confidence weights, frame-proof flags, the current Vimshottari dasha spine, Moon nakshatra, vargas, and a secondary tropical/sidereal comparison.

REQUEST BODY - JSON

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/vedic-chart \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "relocationQuery": "Paris, France",
    "referenceDate": "2026-10-01"
  }'

RESPONSE

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "fullReportAvailable": true,
    "reportMode": "scored_reading",
    "locationLabel": "London, United Kingdom"
  },
  "report": {
    "scoredReading": {
      "domains": [],
      "timingSpine": {},
      "provenance": { "rulesetVersion": "scored-reading-v2" }
    },
    "summary": {
      "topSigns": {
        "tropicalRelocated": ["Capricorn", "Leo", "Libra"],
        "siderealRelocated": ["Sagittarius", "Cancer", "Virgo"]
      },
      "activeDasha": { "label": "Venus-Saturn" },
      "moonNakshatra": { "name": "Rohini", "pada": 2 }
    },
    "comparison": {
      "stable": [],
      "changed": [],
      "relocationSensitive": []
    },
    "domains": []
  }
}

POST/api/v1/vedic-chart/full

Paid full Vedic Chart report for exact birth data. Bearer token required. Costs 3 credits only after payload validation and sufficient-credit checks succeed.

This route returns raw JSON only: the full scored reading plus Western tropical, Tropical Vedic, and sidereal Vedic technical comparison, Vimshottari dasha, nakshatra stack, varga summaries, and predictive domain cards. No HTML is returned.

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/vedic-chart/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "relocationQuery": "Paris, France",
    "includeVargaDeepDive": true,
    "referenceDate": "2026-10-01"
  }'

RESPONSE

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_...",
    "fullReportAvailable": true,
    "reportMode": "scored_reading",
    "locationLabel": "London, United Kingdom"
  },
  "report": {
    "scoredReading": {},
    "westernBaseline": {},
    "tropicalVedic": {},
    "siderealVedic": {},
    "dasha": {},
    "nakshatras": {},
    "vargas": {},
    "domains": []
  }
}

POST/api/v1/natal-reading

Free Natal Reading teaser for exact birth data. No Bearer token required. It casts the chart once and returns a deterministic, receipt-backed reading: a hero answer, placements with dignity, four signatures (rising, Sun, Moon, Saturn), the top three ranked tensions, one gift, one growth lever, and, with subject: "child", a trimmed parenting block written for the adult raising the child. The MCP tool is calculate_natal_reading_teaser.

REQUEST BODY - JSON

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/natal-reading \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "2019-03-14",
    "birthTime": "06:42",
    "locationQuery": "London, UK",
    "subjectName": "Sam",
    "subject": "child"
  }'

RESPONSE

{
  "metadata": {
    "creditsCharged": 0,
    "fullReportAvailable": true,
    "reportMode": "teaser",
    "locationLabel": "London, United Kingdom",
    "houseSystem": "P",
    "subject": "child",
    "generatedAtIso": "2026-08-23T00:00:00.000Z"
  },
  "report": {
    "version": "natal-reading-v1",
    "mode": "child",
    "subjectLabel": "Sam",
    "ageBand": "7-12",
    "teaser": true,
    "hero": { "eyebrow": "Natal reading · for the parent", "title": "...", "summary": "...", "signals": [], "receipt": "..." },
    "chart": { "points": [], "cusps": [], "houseSystem": "P", "asc": 0, "mc": 0, "isDiurnal": true },
    "placements": [],
    "personality": {},
    "dominant": [],
    "signatures": [],
    "tensions": [],
    "gifts": [],
    "configurations": [],
    "growth": [],
    "parenting": { "temperament": [], "needs": [], "helps": [], "backfires": [], "support": [], "cautions": [] },
    "caveats": []
  }
}

POST/api/v1/natal-reading/full

Paid full Natal Reading for exact birth data. Bearer token required. Costs 3 credits only after payload validation and sufficient-credit checks succeed; a failure after the reservation refunds the credits.

This route returns raw JSON only: the untrimmed reading with every tension and its pair-specific reading, the full aspect inventory, up to four gifts, the full growth plan, the Vedic lens, the Placidus/Koch/whole-sign house-frame table, display-only midpoints, and a grounded narrative that is null when no AI provider is available. The reading auto-saves as a natal_reading item for the API-key owner. The MCP tool is calculate_natal_reading.

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/natal-reading/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "2019-03-14",
    "birthTime": "06:42",
    "locationQuery": "London, UK",
    "subjectName": "Sam",
    "houseSystem": "W",
    "subject": "child"
  }'

RESPONSE

{
  "metadata": {
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_...",
    "fullReportAvailable": false,
    "reportMode": "deep",
    "locationLabel": "London, United Kingdom",
    "houseSystem": "W",
    "subject": "child",
    "generatedAtIso": "2026-08-23T00:00:00.000Z"
  },
  "report": {
    "version": "natal-reading-v1",
    "mode": "child",
    "teaser": false,
    "hero": {},
    "chart": {},
    "placements": [],
    "signatures": [],
    "tensions": [],
    "gifts": [],
    "growth": [],
    "parenting": {},
    "houseFrames": { "table": [], "divergences": [] },
    "midpoints": {},
    "caveats": []
  },
  "aiNarrative": { "text": "...", "model": "glm-5.2", "receipts": [] }
}

POST/api/v1/timeline

Free Timeline teaser: past-only proof moments and hinge years from your birth date alone, plus optional retrodiction of up to 5 dated past events against universal age cycles, approximate noon UTC planetary hits, and profection basics. No Bearer token required.

REQUEST BODY - JSON

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/timeline \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "events": [
      {
        "id": "event-1",
        "label": "Moved cities",
        "date": "2019-07-01"
      },
      {
        "id": "event-2",
        "label": "Changed jobs",
        "date": "2021-03-10"
      },
      {
        "id": "event-3",
        "label": "Launched project",
        "date": "2024-11-20"
      }
    ]
  }'

RESPONSE

{
  "metadata": {
    "eventCount": 3,
    "birthTimeMode": "date_only",
    "creditsCharged": 0,
    "fullReportAvailable": false
  },
  "analysis": {
    "events": [
      {
        "label": "Moved cities",
        "ageDecimal": 29.567,
        "universalAgeCycles": [{ "cycleId": "saturn-return-1" }],
        "dateOnlyPlanetaryHits": [
          { "transitingPoint": "saturn", "aspect": "square", "natalPoint": "sun", "orbDegrees": 0.2 }
        ],
        "profection": { "mode": "date_only", "profectionHouse": 6 }
      }
    ],
    "caveats": [
      "Birth time not supplied; house cusps, angles, and Lord of Year are omitted.",
      "Date-only planetary hits use noon UTC birth/event planetary positions; Moon, angles, houses, and exact timing require the full report."
    ]
  }
}

POST/api/v1/timeline/full

Paid full Timeline report for exact birth data. Bearer token required. Costs 3 credits only after payload validation and sufficient-credit checks succeed.

This route runs exact-time natal angles, Fortune and Spirit lots, generated eclipse contacts, event transit windows, annual profections, and optional lifetime transit scanning, then saves the finished report to the authenticated user account.

REQUEST BODY - JSON

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/timeline/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "events": [
      {
        "id": "event-1",
        "label": "Moved cities",
        "date": "2019-07-01"
      },
      {
        "id": "event-2",
        "label": "Changed jobs",
        "date": "2021-03-10"
      },
      {
        "id": "event-3",
        "label": "Launched project",
        "date": "2024-11-20"
      }
    ],
    "eventTransitWindowDays": 30,
    "lifetimeEndDate": "2026-12-31"
  }'

RESPONSE

{
  "metadata": {
    "eventCount": 3,
    "birthTimeMode": "ascendant",
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_...",
    "fullReportAvailable": true,
    "locationLabel": "London, United Kingdom"
  },
  "analysis": {
    "natalLots": {
      "status": "computed",
      "isDiurnal": true,
      "lotOfFortune": { "point": "lot_of_fortune", "signName": "Taurus", "house": 2 },
      "lotOfSpirit": { "point": "lot_of_spirit", "signName": "Pisces", "house": 12 }
    },
    "events": [
      {
        "label": "Moved cities",
        "personalizedTransitHits": [],
        "profection": { "mode": "ascendant", "profectionHouse": 6 }
      }
    ],
    "eclipseHits": [
      {
        "eclipseId": "solar-2026-08-12",
        "natalPoint": "sun",
        "aspect": "conjunction",
        "orbDegrees": 0.8
      }
    ],
    "eclipseContactTimeline": {
      "status": "computed",
      "orbDegrees": 3,
      "eclipseCount": 12
    },
    "transitScan": { "status": "scanned", "windowDays": 30 },
    "lifetimeTransitScan": { "status": "scanned" }
  }
}

POST/api/v1/transits

Calculate all transit aspects for a natal chart over a configurable date range.

☿ REQUEST BODY — JSON

✦ AVAILABLE VALUES

☉ DEFAULTS

Points (Magi 11 + true_node): sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, chiron, true_node

Aspects: conjunction, semi_sextile, sextile, square, trine, quincunx, opposition, parallel, contraparallel

✦ EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/transits \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "startDate": "2026-10-01",
    "rangeDays": 7,
    "transitToTransit": true,
    "transitingPoints": [
      "jupiter",
      "saturn",
      "chiron"
    ],
    "aspects": [
      "conjunction",
      "trine",
      "opposition"
    ]
  }'

☉ RESPONSE

Each hit includes enterAtIso, exactAtIso, and exitAtIso — ISO 8601 UTC.

{
  "metadata": {
    "locationLabel": "London, United Kingdom",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London",
    "ephemerisMode": "SWIEPH",
    "creditsRemaining": 4
  },
  "natal": {
    "julianDayUt": 2448057.927,
    "points": { "sun": 84.23, "moon": 212.45, ... },
    "declinations": { "sun": 23.31, "moon": -5.12, ... }
  },
  "transits": [
    {
      "transitingPoint": "jupiter",
      "natalPoint": "sun",
      "aspect": "trine",
      "aspectDomain": "zodiac",
      "enterAtIso": "2026-03-10T00:00:00.000Z",
      "exactAtIso": "2026-03-18T14:23:00.000Z",
      "exitAtIso": "2026-03-26T00:00:00.000Z",
      "exactOrb": 0.12,
      "exactDifference": 0.12,
      "transitingLongitude": 204.35,
      "natalLongitude": 84.23,
      "isApplying": false
    }
  ]
}

The report above is the 200 body you get when the job finishes inside the short delivery: "auto" wait. Longer scans, and every delivery: "async" call, return a 202 job receipt instead; see Report jobs.

REPORT JOBS: 202, 402 AND POLLING

/api/v1/transits and /api/v1/electional-spellcasting queue a durable job first. The POST answers 200 with the finished report only when it completes within the short auto wait; otherwise it answers 202 with the receipt below, plus Location, Idempotency-Key and x-credits-remaining headers. Credits are reserved when the job is queued and refunded if it fails.

Send an Idempotency-Key header (a new UUID per request, up to 200 characters; a longer or missing key is replaced by a fresh server key) and reuse it when you retry that request. A retry with the same Idempotency-Key and body returns the original receipt without reserving credits again; the same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED.

202 ACCEPTED — JOB RECEIPT

{
  "jobId": "6650f1c2a9e4b3d2c1f0e9a8",
  "idempotencyKey": "client-retry-key-001",
  "kind": "transits",
  "status": "queued",
  "statusUrl": "/api/v1/report-jobs/6650f1c2a9e4b3d2c1f0e9a8",
  "resultUrl": "/api/v1/report-jobs/6650f1c2a9e4b3d2c1f0e9a8/result",
  "forcedAsync": false,
  "billing": {
    "billingVersion": 2,
    "billableMonths": 1,
    "intentCount": 0,
    "chartCount": 1,
    "baseCredits": 1,
    "addonCredits": 0,
    "totalCredits": 1
  },
  "remainingCredits": 24
}

402 — INSUFFICIENT CREDITS (REPORT ROUTES)

The same receipt with status: "rejected". It has no top-level error or code; read failure.code. Replaying its key returns the same rejected receipt, so after adding credits, resubmit with a new Idempotency-Key.

{
  "jobId": "6650f1c2a9e4b3d2c1f0e9a8",
  "idempotencyKey": "client-retry-key-001",
  "kind": "transits",
  "status": "rejected",
  "statusUrl": "/api/v1/report-jobs/6650f1c2a9e4b3d2c1f0e9a8",
  "resultUrl": "/api/v1/report-jobs/6650f1c2a9e4b3d2c1f0e9a8/result",
  "forcedAsync": false,
  "billing": {
    "billingVersion": 2,
    "billableMonths": 1,
    "intentCount": 0,
    "chartCount": 1,
    "baseCredits": 1,
    "addonCredits": 0,
    "totalCredits": 1
  },
  "failure": {
    "code": "INSUFFICIENT_API_CREDITS",
    "message": "Insufficient API credits for this report."
  }
}

402 — INSUFFICIENT CREDITS (SINGLE-CALL ROUTES)

Every other paid route (timeline, month, Vedic and natal full reports, synastry, solar return, AI guidance) answers in one call and returns:

{
  "error": "Insufficient API credits.",
  "code": "INSUFFICIENT_API_CREDITS",
  "remainingCredits": 0
}

POLLING

GET statusUrl until job.status is completed, then GET resultUrl. Statuses: created, queued, running, retry_wait, completed, rejected, failed. Send the same Bearer key. MCP clients use the get_report_job tool.

GET /api/v1/report-jobs/{jobId} RESPONSE

{
  "job": {
    "id": "6650f1c2a9e4b3d2c1f0e9a8",
    "kind": "transits",
    "sourceRoute": "/api/v1/transits",
    "status": "running",
    "progress": {
      "phase": "transit_scan",
      "completedUnits": 0,
      "totalUnits": 1,
      "percent": 0,
      "message": "Scanning transits"
    },
    "summary": {
      "startDate": "2026-10-01",
      "endDate": "2026-11-01",
      "durationDays": 31,
      "intentCount": 0,
      "chartCount": 1
    },
    "execution": {
      "estimatedDurationMs": 45000,
      "forcedAsync": false,
      "queueReason": "wait_budget_elapsed",
      "attempt": 1,
      "maxAttempts": 4,
      "availableAt": "2026-10-01T12:00:00.000Z",
      "startedAt": "2026-10-01T12:00:01.000Z"
    },
    "billing": {
      "version": 2,
      "credits": 1,
      "status": "reserved",
      "remainingCreditsAfterReservation": 24,
      "quote": {
        "billingVersion": 2,
        "billableMonths": 1,
        "intentCount": 0,
        "chartCount": 1,
        "baseCredits": 1,
        "addonCredits": 0,
        "totalCredits": 1
      }
    },
    "createdAt": "2026-10-01T12:00:00.000Z",
    "updatedAt": "2026-10-01T12:00:14.000Z"
  }
}

GET /api/v1/report-jobs/{jobId}/result WHILE ACTIVE (202)

{
  "status": "running",
  "progress": {
    "phase": "transit_scan",
    "completedUnits": 0,
    "totalUnits": 1,
    "percent": 0,
    "message": "Scanning transits"
  }
}

✦ ERROR CODES

POST/api/v1/electional-spellcasting

Generate ranked timing windows for a selected goal using house-first scoring.

Credit model: 1 CREDIT PER INTENT PER BILLABLE CALENDAR MONTH. Transit-to-transit data is still calculated for every electional request, while its scoring contribution can now be disabled through request scoring settings.

Engine: Layered Electional Scoring. 40 live rule layers across 7 ordered passes, with transit-to-natal weighting kept above transit-to-transit refinement.

☽ REQUIRED FIELDS

✦ EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/electional-spellcasting \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "intentId": "career-advancement-promotion",
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "startDate": "2026-10-01",
    "rangeDays": 7,
    "strictness": "standard",
    "scoring": {
      "enabledPasses": [
        "pass1Baseline",
        "pass3IntentFit",
        "pass4NatalCompatibility"
      ],
      "enabledRules": [
        "moon_phase",
        "primary_significator_hits",
        "natal_anchor_hits"
      ],
      "useNatalHouseFrameOnly": false,
      "aspectPotencies": {
        "sextile": 0.35,
        "biquintile": 0.06
      }
    }
  }'

☉ RESPONSE

{
  "metadata": {
    "scanStartDate": "2026-01-01",
    "scanEndDate": "2026-01-31",
    "transitToTransitUsed": true,
    "strictness": "standard",
    "creditsRemaining": 3
  },
  "intent": {
    "id": "career-advancement-promotion",
    "house": 10,
    "polarity": "constructive"
  },
  "windows": [
    {
      "startAtIso": "2026-01-18T00:00:00.000Z",
      "peakAtIso": "2026-01-19T12:00:00.000Z",
      "endAtIso": "2026-01-21T00:00:00.000Z",
      "score": {
        "total": 18.24,
        "pass1Baseline": 3.6,
        "pass2HouseAlignment": 4.55,
        "pass3IntentFit": 4.12,
        "pass4NatalCompatibility": 3.97,
        "pass5Finalization": 2.0
      },
      "planetConditions": [
        {
          "point": "sun",
          "score": 3.6,
          "band": "commanding",
          "house": 10,
          "roles": ["house_ruler"],
          "lineItems": [
            { "label": "DOMICILE", "points": 2.4, "detail": "sun is in domicile in Leo" },
            { "label": "HOUSE STRENGTH", "points": 1.2, "detail": "sun is placed in natal house 10" }
          ]
        }
      ],
      "moonVoidOfCourse": {
        "isVoid": false,
        "nextMoonHitAtIso": "2026-01-19T16:20:00.000Z"
      },
      "integrityDiagnostics": {
        "nearestSyzygy": {
          "kind": "new",
          "exactAtIso": "2026-01-18T19:52:00.000Z",
          "relation": "previous",
          "distanceHours": 16.13,
          "withinFourDaysOfNewMoon": true
        },
        "nextMoonPerfection": {
          "status": "found",
          "exactAtIso": "2026-01-19T16:20:00.000Z",
          "targetPoint": "mars",
          "aspect": "trine",
          "influence": "support",
          "hoursAfterPeak": 4.33
        }
      }
    }
  ],
  "scanDiagnostics": {
    "candidateAudit": { "candidatePeakCount": 14, "minimumVacantSpanHours": 3, "totalVacantSpanCount": 2, "truncatedCount": 0, "spans": [] },
    "maleficAngleAudit": { "status": "complete", "sampleCadenceMinutes": 30, "maxOrbDegrees": 5, "sampledMomentCount": 1489, "failedSampleCount": 0, "totalUnrepresentedIntervalCount": 3, "truncatedCount": 0, "intervals": [] }
  }
}

Like transits, this route returns the report above only when the job finishes inside the auto wait; otherwise it returns the 202 job receipt (or a 402 rejected receipt) described under Report jobs.

Window rationale may include advanced diagnostics already active in production, including natal target condition, return windows, true void-of-course with exact sign-exit time in moonVoidOfCourse.endsAtIso, Via Combusta, besiegement, lots, antiscia, and nodal or translation/perfection notes when present. Asteroid, fixed-star, and galactic discovery contacts are returned in discoveryHits/discoveryHitInsights. Curated catalog members score as bounded minor testimonies in score.pass7DiscoveryContacts (cap 3/-3); matches outside the catalog stay display-only. They never create a candidate window and never define a window's span.

Integrity receipts are observational only. Each window's integrityDiagnostics identifies the nearest exact syzygy and the Moon's next major perfected aspect (or its void/unavailable state). Top-level scanDiagnostics records gaps longer than three hours between candidate exactitudes plus Mars/Saturn-on-ASC/MC intervals that contain no candidate peak. These fields do not alter nomination, scoring, gates, or rank. Multi-chart responses place additional timing-frame audits in chartScanDiagnostics.

With secondChart set, the top-level windows stay the primary chart's results and an additional chartResults array carries one entry per extra chart (chartKey of secondary or composite, its label, per-chart natal geometry, and its own windows). The composite chart uses shortest-arc midpoints, skips declination contacts and annual (solar-return) context, and anchors planetary day/hour timing at the primary chart's location. A relationship field also rides along with the same domain-scored synastry compatibility report returned by /api/v1/synastry, at no extra credit cost.

POST/api/v1/synastry

Domain-scored relationship compatibility for two charts (people or exactly-timed events): marriage & romance, business & partnership, communication, chemistry, stability, and friction — derived from synastry inter-aspects, bidirectional house overlays, and the composite (midpoint) chart's internal aspects. Every domain ships its contributing contacts as receipts.

Credit model: 1 CREDIT per successful report. Raw JSON only; not auto-saved.

☽ REQUEST FIELDS

☉ RESPONSE

{
  "metadata": {
    "chartALabel": "Jordan",
    "chartBLabel": "Riley",
    "chartALocationLabel": "London, United Kingdom",
    "chartBLocationLabel": "Paris, France",
    "ephemerisMode": "SWIEPH",
    "creditsRemaining": 9,
    "houseSystem": "P",
    "orbModel": "planet_class",
    "chartATimeKnown": true,
    "chartBTimeKnown": true
  },
  "relationship": {
    "chartALabel": "Jordan",
    "chartBLabel": "Riley",
    "overall": {
      "percentile": 71,
      "band": "promising",
      "headline": "Stronger than most pairings for Marriage & romance; High friction is the growth edge.",
      "strongestDomainId": "marriage_romance",
      "growthEdgeDomainId": "friction_challenges",
      "confidence": "high",
      "confidenceReasons": [
        "Exact birth times and stable bands across ±30 minutes."
      ]
    },
    "domains": [
      {
        "id": "marriage_romance",
        "label": "Marriage & romance",
        "score": 8.75,
        "maxScore": 14,
        "percent": 63,
        "percentile": 84,
        "rawScore": 9.4,
        "band": "strong",
        "evidence": [
          {
            "kind": "synastry_aspect",
            "label": "Jordan Sun trine Riley Moon (orb 1.2°)",
            "points": 4,
            "detail": "Core identity meets emotional nature — the classic marriage signature."
          }
        ],
        "caveats": [],
        "timeStability": {
          "status": "stable",
          "bandsSeen": [
            "strong"
          ],
          "windowMinutes": 30,
          "percentileRange": [
            80,
            88
          ]
        }
      }
    ],
    "topAspects": [],
    "aspectCounts": {
      "supportive": 6,
      "challenging": 3,
      "charged": 2
    }
  },
  "charts": {
    "a": {
      "points": {}
    },
    "b": {
      "points": {}
    },
    "composite": {
      "points": {}
    }
  }
}

Bands come from percentile (the rank of rawScore against the calibration table), not from percent. relationship.overall carries the verdict and its confidence; timeStability flags a domain as time-sensitive only when shifting either birth time by up to 30 minutes both changes its band and moves its percentile by at least 25 points; smaller band-edge wobbles stay stable.

The friction_challenges domain is inverted: a high percentile means more friction and its band reads accordingly. Domains without qualifying contacts carry an explicit neutral caveat instead of implying a negative verdict; house-overlay evidence requires both exact birth times.

POST/api/v1/daily-elections

Scan all 72 intents across the next 24 hours from the user's browser-time moment and return the strongest window for each intent in one flattened, score-sorted list. Use now mode to score one exact election at browser time.

Auth model: Free: 3 runs per IP per week, no auth needed. Then 1 credit per run with a Bearer key or signed-in session; memberships with unlimited Daily Elections run free. Predictive overlays add +1 credit each, at most +3 credits per run, even for members, and need auth. secondChart (joint mode) costs 2 credits and needs auth; members run it free. Anonymous joint or overlay requests return 402 JOINT_DAILY_AUTH_REQUIRED or 402 PREDICTIVE_OVERLAY_AUTH_REQUIRED; an anonymous caller past the free runs gets 402 FREE_LIMIT_REACHED.

Advanced windowing: optional startTime and endTime narrow the actual scan window inside that rolling 24-hour range. They do not filter a full-range result set after the fact, and they cannot be combined with scanMode: "now".

☿ REQUEST BODY — JSON

✦ EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/daily-elections \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "birthDate": "1990-01-01",
    "birthTime": "12:00",
    "locationQuery": "London, UK",
    "scanMode": "day",
    "browserNowIso": "2026-10-01T07:15:00.000Z",
    "browserTimezone": "Europe/London",
    "startTime": "09:00",
    "endTime": "17:00",
    "scoring": {
      "useNatalHouseFrameOnly": false
    }
  }'

☉ RESPONSE

{
  "metadata": {
    "locationLabel": "London, United Kingdom",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "timezone": "Europe/London",
    "timingTimezone": "Europe/London",
    "ephemerisMode": "SWIEPH",
    "warning": null,
    "relocationLabel": null,
    "relocationLatitude": null,
    "relocationLongitude": null,
    "scanStartDate": "2026-04-08",
    "scanEndDate": "2026-04-08",
    "scanStartIso": "2026-04-08T13:00:00.000Z",
    "scanEndIso": "2026-04-08T21:00:59.999Z",
    "scanMode": "day",
    "startTime": "09:00",
    "endTime": "17:00",
    "scanTimezone": "Europe/London",
    "intentCount": 72,
    "creditsRemaining": null,
    "isFreeUse": true,
    "freeUsage": { "used": 1, "limit": 3, "remaining": 2 }
  },
  "windows": [
    {
      "intentId": "career-advancement-promotion",
      "intentName": "Career Advancement and Promotion",
      "peakAtIso": "2026-04-08T15:20:00.000Z",
      "score": {
        "total": 18.24,
        "pass1Baseline": 3.6,
        "pass2HouseAlignment": 4.55,
        "pass3IntentFit": 4.12,
        "pass4NatalCompatibility": 3.97,
        "pass5Finalization": 2.0
      },
      "planetConditions": [
        {
          "point": "moon",
          "score": 3.1,
          "band": "commanding",
          "house": 11,
          "roles": ["moon"],
          "lineItems": [
            { "label": "EXALTATION", "points": 1.9, "detail": "moon is in exaltation in Taurus" },
            { "label": "HOUSE STRENGTH", "points": 1.2, "detail": "moon is placed in natal house 11" }
          ]
        }
      ],
      "moonVoidOfCourse": {
        "isVoid": true,
        "endsAtIso": "2026-04-08T18:45:00.000Z"
      },
      "integrityDiagnostics": {
        "nearestSyzygy": {
          "kind": "new",
          "exactAtIso": "2026-04-07T11:18:00.000Z",
          "relation": "previous",
          "distanceHours": 28.03,
          "withinFourDaysOfNewMoon": true
        },
        "nextMoonPerfection": { "status": "void", "signExitAtIso": "2026-04-08T18:45:00.000Z" }
      }
    }
  ],
  "scanDiagnostics": {
    "candidateAudit": { "candidatePeakCount": 8, "minimumVacantSpanHours": 3, "totalVacantSpanCount": 1, "truncatedCount": 0, "spans": [] },
    "maleficAngleAudit": { "status": "complete", "sampleCadenceMinutes": 30, "maxOrbDegrees": 5, "sampledMomentCount": 17, "failedSampleCount": 0, "totalUnrepresentedIntervalCount": 2, "truncatedCount": 0, "intervals": [] }
  }
}

Day-mode responses include the same observational integrity receipts as the full electional endpoint: per-window syzygy/next-Moon-perfection context and a shared candidate-gap plus malefic-angle scan audit. They do not affect window selection or ordering. Exact-now mode has no scan interval, so it returns only the per-window receipt.

POST/api/v1/aspect-interpretations/expand

Save an exact aspect interpretation blend for reuse across the app. The permanent key includes chart surface, relationship type, aspect domain, aspect, both points, roles, signs, houses, and dignity; orb and applying/separating state are excluded.

Credit model: 1 CREDIT when the exact blend does not already exist. Existing saved blends return with creditsCharged: 0.

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/aspect-interpretations/expand \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "context": {
      "surface": "transits",
      "relationshipType": "natal_to_transit",
      "aspect": "square",
      "aspectDomain": "zodiac",
      "exactOrb": 0.42,
      "isApplying": true,
      "subject": {
        "point": "sun",
        "role": "transiting",
        "sign": "Leo",
        "house": 11
      },
      "object": {
        "point": "moon",
        "role": "natal",
        "sign": "Scorpio",
        "house": 3
      }
    }
  }'

RESPONSE

{
  "expansionKey": "expand|v1|transits|natal_to_transit|zodiac|transiting|sun|Leo|11|domicile|square|natal|moon|Scorpio|3|fall",
  "created": true,
  "creditsCharged": 1,
  "creditsRemaining": 6,
  "interpretation": {
    "title": "Sun square Moon",
    "summary": "Sun (Leo, H11) square Moon (Scorpio, H3): ...",
    "chartFlavor": "Leo injects expressive visibility into Sun... Sun is in domicile in Leo...",
    "practical": "..."
  }
}

POST/api/v1/ai-guidance

Generate grounded guidance from transit hits, election windows, solar-return dossiers, or Timeline reports. Z.ai GLM is primary; the Gemini Developer API is the automatic fallback.

Credit model: FLAT 3 CREDITS PER REQUEST. The route reserves credits before provider generation, saves successful guidance before returning it, and refunds credits if both providers fail or auto-save fails. Invalid requests, missing provider configuration, and insufficient-credit responses do not call a provider or consume credits.

Guidance is written from a fixed prompt for each domain, orientation and scope; metadata.promptTemplate names the one used. The accepted domain values are sourced from the request schema below; orientation is pragmatic or esoteric, and scope is single or many.

REQUEST BODY - JSON

EXAMPLE REQUEST

# Idempotency-Key: one new UUID per request; reuse the same key when retrying it.
curl -X POST https://electional.io/api/v1/ai-guidance \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <uuid>" \
  -d '{
    "domain": "election",
    "orientation": "esoteric",
    "scope": "many",
    "items": [
      {
        "peakAtIso": "2026-10-01T10:00:00.000Z",
        "score": {
          "total": 18.4
        }
      },
      {
        "peakAtIso": "2026-10-02T12:00:00.000Z",
        "score": {
          "total": 16.9
        }
      }
    ],
    "context": {
      "intent": {
        "name": "Networking"
      }
    },
    "question": "Which window is best for a consecration?"
  }'

RESPONSE

{
  "guidance": "Use the first window for the core rite...",
  "metadata": {
    "domain": "election",
    "orientation": "esoteric",
    "scope": "many",
    "itemCount": 2,
    "creditsCharged": 3,
    "creditsRemaining": 7,
    "model": "glm-5.2",
    "provider": "zai",
    "promptTemplate": "election-esoteric-many.md"
  }
}

⚷ MCP SERVER

A local stdio MCP server for Claude Desktop, Claude Code and other local MCP clients. It exposes every public POST /api/v1 route as a tool against the same live REST API, plus get_report_job for long report jobs.

✦ SETUP

MCP access is in private beta. The server runs locally and is not yet a public package, so email sales@electional.io for the package. The REST API is the supported path today.

# claude_desktop_config.json:
{
  "mcpServers": {
    "electional": {
      "command": "npx",
      "args": [
        "tsx",
        "/ABSOLUTE/PATH/TO/electional-mcp/src/mcp/index.ts"
      ],
      "env": {
        "TRANSITS_API_URL": "https://electional.io",
        "TRANSITS_API_KEY": "sk_tr_your_key_here"
      }
    }
  }
}

INSTALL

1. 1. Email sales@electional.io for the MCP package (private beta), then run npm install in its folder.
2. 2. Download the Claude Desktop template above and open your local MCP config file.
3. 3. Replace /ABSOLUTE/PATH/TO/electional-mcp/src/mcp/index.ts with the full absolute path to the package's src/mcp/index.ts.
4. 4. Keep TRANSITS_API_URL as https://electional.io and set TRANSITS_API_KEY to a live API key from /api-keys.
5. 5. Save the config and fully restart Claude Desktop so the MCP server is reloaded.

Important: desktop MCP clients generally need an absolute file path here. A relative path like src/mcp/index.ts is not reliable outside the package folder.

WHAT YOU GET

The MCP server currently exposes generate_ai_guidance, expand_aspect_interpretation, calculate_daily_elections, calculate_electional_spellcasting, calculate_eclipse_hits, match_goal_to_intents, calculate_month_forecast_teaser, calculate_month_forecast, generate_personality_interpretations, generate_placement_interpretation, calculate_personalized_retrograde_hits, calculate_solar_return, calculate_solar_return_location_election, calculate_synastry_compatibility, calculate_timeline_teaser, calculate_timeline_full_report, generate_transit_interpretations, calculate_transits, calculate_vedic_chart_teaser, calculate_vedic_chart, calculate_vedic_chart_predictions, calculate_natal_reading_teaser, calculate_natal_reading, calculate_proof_synthesis, generate_window_synthesis, get_report_job. All tools call the same live REST API documented on this page. Credit costs match direct API calls; calculate_timeline_full_report uses /api/v1/timeline/full and follows its 3 credits successful-report charge, calculate_month_forecast uses /api/v1/month/full and follows its 3 credits successful-report charge, calculate_vedic_chart uses /api/v1/vedic-chart/full and follows its 3 credits successful-report charge, and calculate_natal_reading uses /api/v1/natal-reading/full and follows its 3 credits successful-report charge (calculate_natal_reading_teaser stays free).