☿ ELECTIONAL — GRIMOIRE

API DOCS

Calculate transit windows and ranked timing results programmatically. ♄ GET API KEY

♄ AUTHENTICATION & BILLING

/api/v1/transits, /api/v1/electional-spellcasting, /api/v1/synastry, /api/v1/timeline/full, /api/v1/month/full, /api/v1/vedic-chart/full, /api/v1/natal-reading/full, /api/v1/aspect-interpretations/expand, and /api/v1/ai-guidance require a Bearer token. Get your key from the API Keys page.

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 1 flat credit when transitToTransit: true. 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 hydrate resultUrl when complete.

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

/api/v1/daily-elections: 3 free uses per IP per week, then 1 credit after a successful scan. Browser users can use an app session; API and MCP clients can send Bearer-token auth.

/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, 5 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. Prompt templates live in prompts/*.md.

/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. The generated endpoint reference below gives a request example, response shape, and consumer notes for every route.

ROUTE	AUTH	CREDITS	MCP TOOL	USE
`/api/v1/ai-guidance`	bearer	3 credits per successful guidance request.	`generate_ai_guidance`	Paid grounded guidance over transit, election, solar-return, or timeline payloads.
`/api/v1/aspect-interpretations/expand`	bearer	1 credit only when a new blend is created.	`expand_aspect_interpretation`	Creates or returns a permanent exact aspect/sign/house/dignity interpretation blend.
`/api/v1/daily-elections`	session_or_bearer	3 free IP uses per week, then 1 credit; paid overlays add credits.	`calculate_daily_elections`	Scans all electional intents for the next 24 hours or scores one exact now chart.
`/api/v1/electional-spellcasting`	bearer	1 credit per intent per billable calendar month, times chart count; overlays are additive.	`calculate_electional_spellcasting`	Finds ranked election windows for one or many intents from one shared scan.
`/api/v1/eclipse-hits`	free	Free; public scans are capped at 10 years.	`calculate_eclipse_hits`	Free exact-time natal eclipse contact checker over a capped public scan range.
`/api/v1/month`	free	Free.	`calculate_month_forecast_teaser`	Free exact-birth Month Ahead forecast shell without persistence.
`/api/v1/month/full`	bearer	5 credits per successful report.	`calculate_month_forecast`	Paid Month Ahead report with generated narrative and auto-save.
`/api/v1/personality-interpretation`	free	Free; cache-miss generation is IP-rate-limited.	`generate_personality_interpretations`	Batch cache endpoint for big-three, pair, and stack personality interpretation text.
`/api/v1/placement-interpretation`	free	Free; generated once per unique placement when configured.	`generate_placement_interpretation`	Cache endpoint for one planet/sign/house placement interpretation.
`/api/v1/retrograde-hits`	free	Free; public scans are capped at 10 years.	`calculate_personalized_retrograde_hits`	Free exact-time Mercury, Venus, and Mars retrograde contact checker.
`/api/v1/solar-return`	bearer	1 credit per successful report.	`calculate_solar_return`	Computes annual profection, solar-return chart context, and SR transit windows.
`/api/v1/solar-return/elect-location`	bearer	3 credits per successful location election.	`calculate_solar_return_location_election`	Ranks birthday cities for a solar-return intent category using the curated city set.
`/api/v1/synastry`	bearer	1 credit per successful compatibility report.	`calculate_synastry_compatibility`	Domain-scored relationship compatibility (marriage, business, and more) from synastry inter-aspects, house overlays, and the composite chart.
`/api/v1/timeline`	free	Free.	`calculate_timeline_teaser`	Free date-only or partial timeline teaser with proof moments and hinge years.
`/api/v1/timeline/full`	bearer	3 credits per successful report.	`calculate_timeline_full_report`	Paid exact-time full timeline with dated-event retrodiction and auto-save.
`/api/v1/transit-interpretation`	free	Free; generated once per unique transit pattern when configured.	`generate_transit_interpretations`	Batch cache endpoint for generic transit-to-natal interpretation text.
`/api/v1/transits`	bearer	1 credit per billable calendar month, times chart count; transit-to-transit and overlays are additive.	`calculate_transits`	Calculates natal-to-transit and optional transit-to-transit aspect hits.
`/api/v1/vedic-chart`	free	Free.	`calculate_vedic_chart_teaser`	Free exact-birth Vedic scored reading with frame comparison and predictive timing.
`/api/v1/vedic-chart/full`	bearer	3 credits per successful report.	`calculate_vedic_chart`	Paid full Vedic Chart report with saved scored reading and deep technical sections.
`/api/v1/vedic-chart/predictions`	free	Free.	`calculate_vedic_chart_predictions`	Free deterministic predictive Vedic report used by the predictions route and overlays.
`/api/v1/natal-reading`	free	Free.	`calculate_natal_reading_teaser`	Free exact-birth natal reading teaser: placements, top tensions, one growth lever, and a child/parenting mode.
`/api/v1/natal-reading/full`	bearer	3 credits per successful report.	`calculate_natal_reading`	Paid full natal reading with every tension's pair-specific reading, full aspect inventory, growth plan, Vedic lens, house-frame comparison, midpoints, grounded AI narrative, and auto-save.
`/api/v1/proof-synthesis`	free	Free.	`calculate_proof_synthesis`	Free cross-system life-guess synthesis: combines Timeline dated cycles with Vedic domain scores into concrete, window-level, falsifiable life guesses.
`/api/v1/window-synthesis`	session_or_ip	Free; anonymous usage is IP-rate-limited.	`generate_window_synthesis`	Free grounded synthesis over rendered election, transit, Vedic, synastry, or natal reading result items.

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.

POST

AI Guidance

/api/v1/ai-guidance

Paid grounded guidance over transit, election, solar-return, or timeline payloads.

AUTH: bearer
CREDITS: 3 credits per successful guidance request.
MCP TOOL: generate_ai_guidance

/api/v1/ai-guidance request example

{
  "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?"
}

/api/v1/ai-guidance response example

{
  "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"
  }
}

CONSUMER NOTES

Send either item for single scope or items for many scope; the schema rejects mixing them.
LLM guidance is grounded against supplied route output and costs a flat 3 credits per successful request.
Bearer-token API clients receive raw JSON only; no saved HTML report is returned.

POST

Aspect Interpretation Expansion

/api/v1/aspect-interpretations/expand

Creates or returns a permanent exact aspect/sign/house/dignity interpretation blend.

AUTH: bearer
CREDITS: 1 credit only when a new blend is created.
MCP TOOL: expand_aspect_interpretation

/api/v1/aspect-interpretations/expand request example

{
  "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"
    }
  }
}

/api/v1/aspect-interpretations/expand response example

{
  "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": []
  }
}

CONSUMER NOTES

The permanent cache key includes surface, relationship type, aspect domain, aspect, roles, points, signs, houses, and dignity.
Orb and applying or separating state are intentionally excluded from the permanent expansion key.
Existing blends return without another credit charge.

POST

Daily Elections

/api/v1/daily-elections

Scans all electional intents for the next 24 hours or scores one exact now chart.

AUTH: session_or_bearer
CREDITS: 3 free IP uses per week, then 1 credit; paid overlays add credits.
MCP TOOL: calculate_daily_elections

/api/v1/daily-elections request example

{
  "birthDate": "1990-06-15",
  "birthTime": "14:30",
  "locationQuery": "New York, NY",
  "scanMode": "day",
  "browserNowIso": "2026-07-01T08:15:00.000-04:00",
  "browserTimezone": "America/New_York",
  "startTime": "09:00",
  "endTime": "17:00",
  "scoring": {
    "useNatalHouseFrameOnly": false
  }
}

/api/v1/daily-elections response example

{
  "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"
      }
    }
  ]
}

CONSUMER NOTES

Anonymous clients get 3 free IP uses per week; valid Bearer tokens identify the account for MCP/API usage.
startTime and endTime narrow the scan window before scoring and cannot be used with scanMode now.
Results are flat and score-sorted by default; intent grouping is a UI/client concern.

POST

Electional Spellcasting

/api/v1/electional-spellcasting

Finds ranked election windows for one or many intents from one shared scan.

AUTH: bearer
CREDITS: 1 credit per intent per billable calendar month, times chart count; overlays are additive.
MCP TOOL: calculate_electional_spellcasting

/api/v1/electional-spellcasting request example

{
  "intentId": "career-advancement-promotion",
  "birthDate": "1990-06-15",
  "birthTime": "14:30",
  "locationQuery": "New York, NY",
  "rangeDays": 7,
  "strictness": "standard",
  "maxWindows": 3,
  "scoring": {
    "enabledPasses": [
      "pass1Baseline",
      "pass3IntentFit",
      "pass4NatalCompatibility"
    ],
    "useNatalHouseFrameOnly": false
  }
}

/api/v1/electional-spellcasting response example

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

CONSUMER NOTES

Credits are charged by scan length; selected paid overlays can add credits.
Transit-to-natal hits dominate plain transit-to-transit refinement in scoring.
Every window carries pass-level receipts and diagnostic context for consumer-side explanation.

POST

Eclipse Hits

/api/v1/eclipse-hits

Free exact-time natal eclipse contact checker over a capped public scan range.

AUTH: free
CREDITS: Free; public scans are capped at 10 years.
MCP TOOL: calculate_eclipse_hits

/api/v1/eclipse-hits request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-01-01",
  "endDate": "2030-12-31",
  "orbDegrees": 3
}

/api/v1/eclipse-hits response example

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "locationLabel": "Dunedin, FL, USA",
    "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
    }
  ]
}

CONSUMER NOTES

This v1 route reuses the free eclipse checker contract behind /api/free/eclipse-hits.
Exact birth data is required because natal angles are part of the contact set.
Public scan windows are capped at 10 years and charge 0 credits.

POST

Month Ahead Teaser

/api/v1/month

Free exact-birth Month Ahead forecast shell without persistence.

AUTH: free
CREDITS: Free.
MCP TOOL: calculate_month_forecast_teaser

/api/v1/month request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-07-01"
}

/api/v1/month response example

{
  "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
}

CONSUMER NOTES

Free teaser route; no Bearer token and no persistence.
Requires exact birth data plus startDate; defaults to a 30-day forecast when days is omitted.
Use the full route when the generated narrative and saved report id are required.

POST

Month Ahead Full Report

/api/v1/month/full

Paid Month Ahead report with generated narrative and auto-save.

AUTH: bearer
CREDITS: 5 credits per successful report.
MCP TOOL: calculate_month_forecast

/api/v1/month/full request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-07-01",
  "days": 30
}

/api/v1/month/full response example

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

CONSUMER NOTES

Bearer token required; the report is auto-saved to the API-key owner.
Credits are refunded on post-reservation generation or save failure.
The response is raw JSON; clients render their own report view.

POST

Personality Interpretation

/api/v1/personality-interpretation

Batch cache endpoint for big-three, pair, and stack personality interpretation text.

AUTH: free
CREDITS: Free; cache-miss generation is IP-rate-limited.
MCP TOOL: generate_personality_interpretations

/api/v1/personality-interpretation request example

{
  "items": [
    {
      "tier": "bigthree",
      "sunSign": "Sagittarius",
      "moonSign": "Pisces",
      "ascSign": "Gemini"
    }
  ]
}

/api/v1/personality-interpretation response example

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

CONSUMER NOTES

Accepts up to 40 items and silently drops malformed items after normalization.
Cache hits are unlimited; cache-miss generation is IP-rate-limited.
The endpoint returns generic reusable text and does not consume credits.

POST

Placement Interpretation

/api/v1/placement-interpretation

Cache endpoint for one planet/sign/house placement interpretation.

AUTH: free
CREDITS: Free; generated once per unique placement when configured.
MCP TOOL: generate_placement_interpretation

/api/v1/placement-interpretation request example

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

/api/v1/placement-interpretation response example

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

CONSUMER NOTES

One placement is generated and cached forever per point/sign/house combination.
No credits are charged; a missing AI configuration returns 503 on cache miss.
Use lowercase or display-case point/sign inputs; the route normalizes them before caching.

POST

Personalized Retrograde Hits

/api/v1/retrograde-hits

Free exact-time Mercury, Venus, and Mars retrograde contact checker.

AUTH: free
CREDITS: Free; public scans are capped at 10 years.
MCP TOOL: calculate_personalized_retrograde_hits

/api/v1/retrograde-hits request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-01-01",
  "endDate": "2030-12-31",
  "orbDegrees": 3
}

/api/v1/retrograde-hits response example

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "locationLabel": "Dunedin, FL, USA",
    "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"
      }
    }
  ]
}

CONSUMER NOTES

This v1 route reuses the free personalized retrograde checker behind /api/free/retrograde-hits.
Exact birth data is required because house and angle contacts are birth-time sensitive.
It filters to Mercury, Venus, and Mars retrograde or station-grade contacts and charges 0 credits.

POST

Solar Return

/api/v1/solar-return

Computes annual profection, solar-return chart context, and SR transit windows.

AUTH: bearer
CREDITS: 1 credit per successful report.
MCP TOOL: calculate_solar_return

/api/v1/solar-return request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "solarReturn": {
    "enabled": true,
    "returnMode": "tropical_non_precessed",
    "locationBasis": "natal"
  }
}

/api/v1/solar-return response example

{
  "metadata": {
    "locationLabel": "Dunedin, FL, USA",
    "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": []
}

CONSUMER NOTES

Bearer token required; costs 1 credit after validation and successful computation.
The endpoint always computes annual context even though the shared solarReturn option can disable scoring side effects elsewhere.
The natal chart remains birth-based; return-location options only frame the solar-return chart.

POST

Solar Return Location Election

/api/v1/solar-return/elect-location

Ranks birthday cities for a solar-return intent category using the curated city set.

AUTH: bearer
CREDITS: 3 credits per successful location election.
MCP TOOL: calculate_solar_return_location_election

/api/v1/solar-return/elect-location request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "intentCategory": "CAREER",
  "returnMode": "tropical_non_precessed",
  "topN": 10
}

/api/v1/solar-return/elect-location response example

{
  "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": []
    }
  ]
}

CONSUMER NOTES

Bearer token required; costs 3 credits per successful location election.
The curated city universe is population-filtered; topN may be 1 through 50.
Only the solar-return frame moves per candidate; the natal chart is never relocated.

POST

Synastry Compatibility

/api/v1/synastry

Domain-scored relationship compatibility (marriage, business, and more) from synastry inter-aspects, house overlays, and the composite chart.

AUTH: bearer
CREDITS: 1 credit per successful compatibility report.
MCP TOOL: calculate_synastry_compatibility

/api/v1/synastry request example

{
  "chartA": {
    "label": "Jordan",
    "birthDate": "1990-06-15",
    "birthTime": "14:30",
    "locationQuery": "New York, NY"
  },
  "chartB": {
    "label": "Riley",
    "birthDate": "1992-03-20",
    "birthTime": "08:15",
    "locationQuery": "Paris, France"
  },
  "orbDegrees": 3
}

/api/v1/synastry response example

{
  "metadata": {
    "chartALabel": "Jordan",
    "chartBLabel": "Riley",
    "ephemerisMode": "SWIEPH",
    "creditsRemaining": 9
  },
  "relationship": {
    "chartALabel": "Jordan",
    "chartBLabel": "Riley",
    "domains": [
      {
        "id": "marriage_romance",
        "label": "Marriage & romance",
        "score": 8.75,
        "maxScore": 14,
        "percent": 63,
        "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": []
      }
    ],
    "topAspects": [],
    "aspectCounts": {
      "supportive": 6,
      "challenging": 3,
      "charged": 2
    }
  },
  "charts": {
    "a": {
      "points": {}
    },
    "b": {
      "points": {}
    },
    "composite": {
      "points": {}
    }
  }
}

CONSUMER NOTES

Both charts may be people or exactly-timed events; each needs date, time, and location.
Every domain score ships its contributing contacts as receipts; treat bands without evidence as neutral.
The friction domain is inverted: a high percent means more friction, and its band reads accordingly.
The response is raw JSON and is not auto-saved.

POST

Timeline Teaser

/api/v1/timeline

Free date-only or partial timeline teaser with proof moments and hinge years.

AUTH: free
CREDITS: Free.
MCP TOOL: calculate_timeline_teaser

/api/v1/timeline request example

{
  "birthDate": "1989-12-06",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    }
  ]
}

/api/v1/timeline response example

{
  "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": []
  }
}

CONSUMER NOTES

Free and unauthenticated; accepts birthDate plus up to 5 optional dated events.
Date-only analysis omits angles, houses, lots, and exact-time transit windows.
Use the full route for exact-birth lifetime scanning and auto-save behavior.

POST

Timeline Full Report

/api/v1/timeline/full

Paid exact-time full timeline with dated-event retrodiction and auto-save.

AUTH: bearer
CREDITS: 3 credits per successful report.
MCP TOOL: calculate_timeline_full_report

/api/v1/timeline/full request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "events": [
    {
      "id": "event-1",
      "label": "Moved cities",
      "date": "2019-07-01"
    },
    {
      "id": "event-2",
      "label": "Changed jobs",
      "date": "2021-03-10"
    }
  ],
  "eventTransitWindowDays": 30,
  "lifetimeEndDate": "2026-12-31"
}

/api/v1/timeline/full response example

{
  "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": "..."
  }
}

CONSUMER NOTES

Bearer token and exact birth data are required; successful reports cost 3 credits.
The full report auto-saves as a timeline item for the API-key owner.
Event and lifetime scans may be CPU-heavy; consumers should keep event counts and date ranges intentional.

POST

Transit Interpretation

/api/v1/transit-interpretation

Batch cache endpoint for generic transit-to-natal interpretation text.

AUTH: free
CREDITS: Free; generated once per unique transit pattern when configured.
MCP TOOL: generate_transit_interpretations

/api/v1/transit-interpretation request example

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

/api/v1/transit-interpretation response example

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

CONSUMER NOTES

Accepts up to 40 items and dedupes by the normalized transit interpretation key.
Malformed items are skipped; an empty normalized set returns an empty interpretations array.
This generic cache endpoint is free and separate from paid aspect-tooltip expansions.

POST

Transits

/api/v1/transits

Calculates natal-to-transit and optional transit-to-transit aspect hits.

AUTH: bearer
CREDITS: 1 credit per billable calendar month, times chart count; transit-to-transit and overlays are additive.
MCP TOOL: calculate_transits

/api/v1/transits request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "startDate": "2026-07-01",
  "rangeDays": 14,
  "transitToTransit": true,
  "transitingPoints": [
    "jupiter",
    "saturn",
    "chiron"
  ],
  "aspects": [
    "conjunction",
    "trine",
    "opposition"
  ]
}

/api/v1/transits response example

{
  "metadata": {
    "locationLabel": "Dunedin, FL, USA",
    "timezone": "America/New_York",
    "ephemerisMode": "SWIEPH",
    "creditsRemaining": 4
  },
  "natal": {
    "points": {
      "sun": 254.23,
      "moon": 12.45
    }
  },
  "transits": [
    {
      "transitingPoint": "jupiter",
      "natalPoint": "sun",
      "aspect": "trine",
      "enterAtIso": "2026-07-03T00:00:00.000Z",
      "exactAtIso": "2026-07-08T14:23:00.000Z",
      "exitAtIso": "2026-07-12T00:00:00.000Z",
      "exactOrb": 0.12
    }
  ],
  "annualContext": null
}

CONSUMER NOTES

Bearer token required; charges 1 credit per billable calendar month times chart count, plus optional add-ons.
Provide either locationQuery or latitude plus longitude; relocation settings affect transit frame only.
Each transit hit includes enter/exact/exit ISO timestamps when a span can be resolved.
Optional secondChart (person or event) scans the second and composite charts too (monthly base credits ×3) and returns chartResults plus a synastry relationship compatibility report.

POST

Vedic Chart Teaser

/api/v1/vedic-chart

Free exact-birth Vedic scored reading with frame comparison and predictive timing.

AUTH: free
CREDITS: Free.
MCP TOOL: calculate_vedic_chart_teaser

/api/v1/vedic-chart request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "relocationQuery": "Boulder, CO",
  "reportMode": "scored_reading"
}

/api/v1/vedic-chart response example

{
  "metadata": {
    "version": "v1",
    "locationLabel": "Dunedin, FL, USA",
    "frames": [
      "western_tropical",
      "tropical_vedic",
      "sidereal_vedic"
    ]
  },
  "comparisonFrames": [],
  "domains": [
    {
      "id": "career",
      "label": "Career",
      "headline": "Visible public-role emphasis.",
      "score": 78
    }
  ],
  "dashaClock": {
    "referenceDateIso": "2026-07-01T00:00:00.000Z",
    "current": [],
    "next": []
  },
  "vargas": [],
  "nakshatras": null
}

CONSUMER NOTES

Free exact-birth scored reading; no Bearer token or persistence.
Public copy should call this Vedic Chart, not True Signs.
The contract distinguishes Western tropical, Tropical Vedic, and Lahiri sidereal comparison frames.

POST

Vedic Chart Full Report

/api/v1/vedic-chart/full

Paid full Vedic Chart report with saved scored reading and deep technical sections.

AUTH: bearer
CREDITS: 3 credits per successful report.
MCP TOOL: calculate_vedic_chart

/api/v1/vedic-chart/full request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "relocationQuery": "Boulder, CO",
  "includeVargaDeepDive": true,
  "reportMode": "scored_reading"
}

/api/v1/vedic-chart/full response example

{
  "metadata": {
    "version": "v1",
    "locationLabel": "Dunedin, FL, USA",
    "frames": [
      "western_tropical",
      "tropical_vedic",
      "sidereal_vedic"
    ],
    "savedItemId": "calc_vedic_123"
  },
  "comparisonFrames": [],
  "domains": [],
  "dashaClock": null,
  "predictiveWindows": [],
  "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))"
      ]
    }
  ]
}

CONSUMER NOTES

Bearer token required; successful full reports cost 3 credits and auto-save to the user account.
vargaDeepDives carries all sixteen evaluated Shodashavarga readings with receipted findings.
Use includeVargaDeepDive when the consumer needs technical varga sections.
The response is raw JSON and preserves the frame-comparison evidence rather than returning HTML.

POST

Vedic Chart Predictions

/api/v1/vedic-chart/predictions

Free deterministic predictive Vedic report used by the predictions route and overlays.

AUTH: free
CREDITS: Free.
MCP TOOL: calculate_vedic_chart_predictions

/api/v1/vedic-chart/predictions request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "pastEvents": [
    {
      "date": "2021-03-10",
      "label": "Changed jobs"
    }
  ],
  "includePredictive": true
}

/api/v1/vedic-chart/predictions response example

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

CONSUMER NOTES

Free deterministic predictive endpoint using the same Vedic request schema.
Past events are optional and capped at 5; they are used as retrodictive calibration evidence.
This endpoint is for JSON consumers and overlays, not the public Vedic Chart landing copy.

POST

Natal Reading Teaser

/api/v1/natal-reading

Free exact-birth natal reading teaser: placements, top tensions, one growth lever, and a child/parenting mode.

AUTH: free
CREDITS: Free.
MCP TOOL: calculate_natal_reading_teaser

/api/v1/natal-reading request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "houseSystem": "P",
  "subject": "self",
  "includeLilith": true
}

/api/v1/natal-reading response example

{
  "metadata": {
    "creditsCharged": 0,
    "fullReportAvailable": true,
    "reportMode": "teaser",
    "locationLabel": "Dunedin, FL, USA",
    "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."
    ]
  }
}

CONSUMER NOTES

Free, no bearer token: requires exact birth date, time, and place (city query or latitude/longitude).
subject "child" switches to parenting mode: tendencies, what helps, what backfires; romance, sexuality, and career-legacy domains are never named for minors.
Teaser responses are trimmed (top 3 tensions, one growth lever, empty aspect inventory, no house-frame table or midpoints); use /api/v1/natal-reading/full for the complete reading.
Every interpretive item carries a receipt such as "Venus ♋ 4th □ Saturn ♈ 1st, 1.8°"; tensions surface only within 6 degrees in exact/tight/moderate tiers.

POST

Natal Reading Full Report

/api/v1/natal-reading/full

Paid full natal reading with every tension's pair-specific reading, full aspect inventory, growth plan, Vedic lens, house-frame comparison, midpoints, grounded AI narrative, and auto-save.

AUTH: bearer
CREDITS: 3 credits per successful report.
MCP TOOL: calculate_natal_reading

/api/v1/natal-reading/full request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "referenceDate": "2026-07-01",
  "houseSystem": "P",
  "subject": "child",
  "subjectName": "Eli"
}

/api/v1/natal-reading/full response example

{
  "metadata": {
    "creditsCharged": 3,
    "creditsRemaining": 7,
    "fullReportAvailable": true,
    "reportMode": "deep",
    "locationLabel": "Dunedin, FL, USA",
    "houseSystem": "P",
    "subject": "child",
    "savedItemId": "calc_natal_123",
    "generatedAtIso": "2026-08-23T12:00:00.000Z"
  },
  "report": {
    "version": "natal-reading-v1",
    "mode": "child",
    "subjectLabel": "Eli",
    "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"
    ]
  }
}

CONSUMER NOTES

Bearer token required; successful full reports cost 3 credits, auto-save as a natal_reading item, and refund on failure.
aiNarrative is nullable: the deterministic report always ships and the grounded narrative degrades to null when the provider is down or the output stays ungrounded.
The session equivalent is POST /api/calculations/natal-reading (durable report job); this route returns the finished JSON synchronously.

POST

Proof Synthesis

/api/v1/proof-synthesis

Free cross-system life-guess synthesis: combines Timeline dated cycles with Vedic domain scores into concrete, window-level, falsifiable life guesses.

AUTH: free
CREDITS: Free.
MCP TOOL: calculate_proof_synthesis

/api/v1/proof-synthesis request example

{
  "birthDate": "1989-12-06",
  "birthTime": "13:17",
  "locationQuery": "Dunedin, FL",
  "houseSystem": "P"
}

/api/v1/proof-synthesis response example

{
  "metadata": {
    "creditsCharged": 0,
    "birthTimeMode": "exact",
    "locationLabel": "Dunedin, FL, USA",
    "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
}

CONSUMER NOTES

Free, no bearer token: requires exact birth date, time, and place; reuses the Vedic chart request schema.
Combines Timeline dated cycles and Vedic domain scores into concrete, window-level, falsifiable life guesses.
Guesses are window-level only; the deterministic evidence bundle always ships and the AI guess layer degrades to an empty list when the provider is down.
Optional streaming: send `Accept: application/x-ndjson` to receive two NDJSON events — `{type:"evidence"}` (deterministic report, fast) then `{type:"complete"}` (full report with AI guesses). Default JSON behavior is unchanged.

POST

Window Synthesis

/api/v1/window-synthesis

Free grounded synthesis over rendered election, transit, Vedic, synastry, or natal reading result items.

AUTH: session_or_ip
CREDITS: Free; anonymous usage is IP-rate-limited.
MCP TOOL: generate_window_synthesis

/api/v1/window-synthesis request example

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

/api/v1/window-synthesis response example

{
  "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."
    ]
  }
}

CONSUMER NOTES

Accepts election, transits, vedic, synastry, or natal domains and up to 96 items after truncation.
Anonymous usage is IP-rate-limited; signed-in users bypass the weekly anonymous cap.
Failures degrade to synthesis null so clients should keep deterministic fallback copy.

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

FIELD	TYPE	DEFAULT	DESCRIPTION
`birthDate`*	string	REQ	Birth date YYYY-MM-DD.
`birthTime`*	string	REQ	Exact birth time HH:MM.
`locationQuery`	string?	—	City search, e.g. "Denver, CO"; required unless latitude and longitude are supplied.
`latitude`	number?	—	Birth latitude. Must be supplied with longitude when no locationQuery is used.
`longitude`	number?	—	Birth longitude. Must be supplied with latitude when no locationQuery is used.
`timezone`	string?	—	Optional IANA timezone override.
`startDate`*	string	REQ	Forecast start date YYYY-MM-DD.
`days`	integer	30	Forecast length. Range 1-62.
`houseSystem`	string	P	House system for exact-time chart framing.

EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/month \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1989-12-06",
    "birthTime": "13:17",
    "locationQuery": "Dunedin, FL",
    "startDate": "2026-07-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 5 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

curl -X POST https://your-domain.com/api/v1/month/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1989-12-06",
    "birthTime": "13:17",
    "locationQuery": "Dunedin, FL",
    "startDate": "2026-07-01",
    "days": 30
  }'

RESPONSE

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 5,
    "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

FIELD	TYPE	DEFAULT	DESCRIPTION
`birthDate`*	string	REQ	Birth date YYYY-MM-DD.
`birthTime`*	string	REQ	Exact birth time HH:MM.
`locationQuery`	string?	—	City search, e.g. "Denver, CO"; required unless latitude and longitude are supplied.
`latitude`	number?	—	Birth latitude. Must be supplied with longitude when no locationQuery is used.
`longitude`	number?	—	Birth longitude. Must be supplied with latitude when no locationQuery is used.
`timezone`	string?	—	Optional IANA timezone override.
`houseSystem`	string	P	House system for lagna, houses, and comparison frames.
`relocationQuery`	string?	—	Optional current or relocated city, e.g. "Boulder, CO".
`frames`	array?	all	western_tropical, tropical_vedic, sidereal_vedic.
`reportMode`	string	scored_reading	scored_reading for the default domain tables; compare keeps the legacy comparison-first contract reachable.
`includePredictive`	boolean	true	Include dasha and life-domain timing sections.
`includeVargaDeepDive`	boolean	false	Include technical varga grids when true.
`referenceDate`	string?	—	YYYY-MM-DD date used for the active dasha clock.

EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/vedic-chart \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1989-12-06",
    "birthTime": "13:17",
    "locationQuery": "Dunedin, FL",
    "relocationQuery": "Boulder, CO",
    "referenceDate": "2026-06-25"
  }'

RESPONSE

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 0,
    "fullReportAvailable": true,
    "reportMode": "scored_reading",
    "locationLabel": "Dunedin, FL, USA"
  },
  "report": {
    "scoredReading": {
      "domains": [],
      "timingSpine": {},
      "provenance": { "rulesetVersion": "scored-reading-v2" }
    },
    "summary": {
      "topSigns": {
        "tropicalRelocated": ["Gemini", "Sagittarius", "Aquarius"],
        "siderealRelocated": ["Scorpio", "Cancer", "Libra"]
      },
      "activeDasha": { "label": "Mercury-Jupiter" },
      "moonNakshatra": { "name": "Purva Bhadrapada", "pada": 4 }
    },
    "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

curl -X POST https://your-domain.com/api/v1/vedic-chart/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1989-12-06",
    "birthTime": "13:17",
    "locationQuery": "Dunedin, FL",
    "relocationQuery": "Boulder, CO",
    "includeVargaDeepDive": true,
    "referenceDate": "2026-06-25"
  }'

RESPONSE

{
  "metadata": {
    "birthTimeMode": "exact",
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_...",
    "fullReportAvailable": true,
    "reportMode": "scored_reading",
    "locationLabel": "Dunedin, FL, USA"
  },
  "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

FIELD	TYPE	DEFAULT	DESCRIPTION
`birthDate`*	string	REQ	Birth date YYYY-MM-DD (1900 through next year).
`birthTime`*	string	REQ	Exact birth time HH:MM. Rising sign and houses need it; there is no date-only mode.
`locationQuery`	string?	—	City search, e.g. "Denver, CO"; required unless latitude and longitude are supplied.
`latitude`	number?	—	Birth latitude. Must be supplied with longitude when no locationQuery is used.
`longitude`	number?	—	Birth longitude. Must be supplied with latitude when no locationQuery is used.
`timezone`	string?	—	Optional IANA timezone override; otherwise resolved from the coordinates.
`houseSystem`	string	P	Primary house frame. Placidus, Koch, and whole-sign are always also cast for the comparison table.
`subject`	string	self	self or child. child switches the framing layer: parent-addressed copy, no Lilith, no adult themes.
`subjectName`	string?	—	Optional name (letters, spaces, apostrophes, hyphens; max 40) used to address a child reading.
`includeLilith`	boolean	true	false drops Black Moon Lilith from signatures, tensions, and growth levers.
`referenceDate`	string?	—	YYYY-MM-DD used only for the child age band; defaults to the generation date.

EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/natal-reading \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "2019-03-14",
    "birthTime": "06:42",
    "locationQuery": "Dunedin, FL",
    "subject": "child",
    "subjectName": "Eli"
  }'

RESPONSE

{
  "metadata": {
    "creditsCharged": 0,
    "fullReportAvailable": true,
    "reportMode": "teaser",
    "locationLabel": "Dunedin, FL, USA",
    "houseSystem": "P",
    "subject": "child",
    "generatedAtIso": "2026-08-23T00:00:00.000Z"
  },
  "report": {
    "version": "natal-reading-v1",
    "mode": "child",
    "subjectLabel": "Eli",
    "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

curl -X POST https://your-domain.com/api/v1/natal-reading/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "2019-03-14",
    "birthTime": "06:42",
    "locationQuery": "Dunedin, FL",
    "houseSystem": "W",
    "subject": "child",
    "subjectName": "Eli"
  }'

RESPONSE

{
  "metadata": {
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_...",
    "fullReportAvailable": false,
    "reportMode": "deep",
    "locationLabel": "Dunedin, FL, USA",
    "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

FIELD	TYPE	DEFAULT	DESCRIPTION
`birthDate`*	string	REQ	Birth date YYYY-MM-DD.
`natalAscLongitude`	number?	—	Optional natal Ascendant longitude, 0 <= longitude < 360, used to name profected sign and Lord of Year.
`events`	array?	[]	Up to 5 optional dated events shaped as { id, label, date }.

EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/timeline \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1989-12-06",
    "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

FIELD	TYPE	DEFAULT	DESCRIPTION
`birthDate`*	string	REQ	Birth date YYYY-MM-DD.
`birthTime`*	string	REQ	Exact birth time HH:MM.
`locationQuery`	string?	—	City search, e.g. "Denver, CO"; required unless latitude and longitude are supplied.
`latitude`	number?	—	Birth latitude. Must be supplied with longitude when no locationQuery is used.
`longitude`	number?	—	Birth longitude. Must be supplied with latitude when no locationQuery is used.
`timezone`	string?	—	Optional IANA timezone override for the birth location.
`houseSystem`	string	P	House system for natal angles and profected house labels.
`events`	array?	[]	Up to 5 optional dated events shaped as { id, label, date }.
`eventTransitWindowDays`	integer	30	Days to scan around each dated event. Range 1-90.
`lifetimeEndDate`	string?	—	Optional YYYY-MM-DD end date for a lifetime transit scan; must be after birthDate.

EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/timeline/full \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1989-12-06",
    "birthTime": "14:30",
    "locationQuery": "Denver, CO",
    "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-06-02"
  }'

RESPONSE

{
  "metadata": {
    "eventCount": 3,
    "birthTimeMode": "ascendant",
    "creditsCharged": 3,
    "creditsRemaining": 12,
    "savedItemId": "calc_...",
    "fullReportAvailable": true,
    "locationLabel": "Denver, CO, USA"
  },
  "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

FIELD	TYPE	DEFAULT	DESCRIPTION
`birthDate`*	string	REQ	Birth date YYYY-MM-DD.
`birthTime`*	string	REQ	Birth time HH:MM (24h).
`locationQuery`	string?	—	City search, e.g. "Paris, France".
`latitude`	number?	—	Birth latitude (-90..90).
`longitude`	number?	—	Birth longitude (-180..180).
`timezone`	string?	—	IANA tz override.
`startDate`	string?	today	Scan start YYYY-MM-DD.
`endDate`	string?	+7d	Scan end YYYY-MM-DD.
`rangeDays`	integer?	7	Compatibility duration; normalized to an absolute end date. Maximum one calendar year.
`delivery`	string?	auto	"auto" briefly waits for short jobs; "async" always returns 202. Five-minute estimates are forced async.
`transitingPoints`	string[]	Magi 11	Transiting bodies.
`natalPoints`	string[]	Magi 11	Natal points.
`aspects`	string[]	Magi 9	Aspect types.
`orbDegrees`	number	3	Longitude orb (0.01-6).
`declinationOrbDegrees`	number	1.2	Declination orb (0.01-3).
`houseSystem`	string	P	House system for angles.
`transitToTransit`	boolean	false	Optional transit-to-transit sky-pattern hits (one flat additional credit).
`asteroidFinder`	boolean	true	Find top discoverable asteroid contacts at 1 degree conjunction/opposition only.
`fixedStarFinder`	boolean	false	Find top-ten fixed-star plus galactic-point contacts at 1 degree conjunction/opposition only.
`midpoints`	boolean	false	Include the natal Ebertin midpoint layer (Sun/Moon + ASC/MC midpoints, midpoint pictures) plus transit-to-midpoint activation windows over the scanned range. No extra credits.
`secondChart`	object?	—	Optional second chart (person or exactly-timed event; same fields as the electional secondChart). The scan also runs for this chart and the composite (midpoint) chart — monthly base credits ×3 — and the response adds chartResults plus a synastry compatibility report.

✦ AVAILABLE VALUES

TRANSITING / NATAL (PLANETS)

sunmoonmercuryvenusmarsjupitersaturnuranusneptuneplutotrue_nodemean_nodechironlilith

ASTEROIDS

cerespallasjunovestahygieaerospsychesapphoastraeapholus

FIXED STARS

spicaregulusaldebaranantaresalgolsiriusfomalhautvegadeneb_algedialcyone

GALACTIC POINTS

galactic_centergreat_attractor

NATAL (ANGLES)

ascmc

ASPECTS

conjunctionsemi_sextilesemi_squaresextilequintilesquaretrinesesquisquarebiquintilequincunxoppositionparallelcontraparallel

HOUSE SYSTEM

PKORCEVW

☉ DEFAULTS — MAGI ASTROLOGY

Points: sun, moon, mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, chiron

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

✦ EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/transits \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-06-15",
    "birthTime": "14:30",
    "locationQuery": "New York, NY",
    "startDate": "2026-01-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": "New York, NY, USA",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York",
    "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
    }
  ]
}

✦ INSUFFICIENT CREDIT RESPONSE

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

✦ ERROR CODES

STATUS	MEANING
401	Missing, invalid, or revoked API key.
402	Insufficient API credits.
400	Invalid request body.
500	Server calculation error.

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

FIELD	TYPE	DEFAULT	DESCRIPTION
`intentId`	string?	—	Singular timing goal; provide exactly one of intentId or intentIds.
`intentIds`	string[]?	—	One to 72 unique timing goals, scored from one shared scan.
`birthDate`*	string	REQ	Birth date YYYY-MM-DD.
`birthTime`*	string	REQ	Birth time HH:MM (24h).
`locationQuery`	string?	—	City search text.
`latitude`	number?	—	Latitude coordinate.
`longitude`	number?	—	Longitude coordinate.
`timezone`	string?	—	Birth timezone override for natal conversion.
`startDate`	string?	today	Scan start.
`endDate`	string?	+7d	Scan end.
`rangeDays`	integer?	7	Compatibility duration; normalized to an absolute end date. Maximum one calendar year.
`delivery`	string?	auto	"auto" briefly waits for short jobs; "async" always returns 202. Five-minute estimates are forced async.
`transitingPoints`	string[]	Magi 11	Transiting bodies included in scoring and chart output.
`aspects`	string[]	All 13	Transit aspect types to calculate. Session-based UI requests fall back to saved account defaults.
`orbDegrees`	number	3	Longitude orb (0.01-6).
`declinationOrbDegrees`	number	1.2	Declination orb (0.01-3).
`houseSystem`	string	P	House system for angles and cusps.
`strictness`	string	standard	"relaxed" \| "standard" \| "strict".
`natalWeight`	number	1	Natal weight (0-2).
`maxWindows`	integer	2	Max windows (1-20).
`asteroidFinder`	boolean	true	Find asteroid discovery contacts at 1 degree conjunction/opposition only; curated ones add a small hard-capped Pass 7 contribution and never create a window.
`fixedStarFinder`	boolean	true	Find top-ten fixed-star plus galactic-point discovery contacts at 1 degree conjunction/opposition only; curated ones add a small hard-capped Pass 7 contribution and never create a window.
`scoring.enabledPasses`	string[]?	All 7	Optional pass ids to keep active in the returned score.
`scoring.enabledRules`	string[]?	All rule groups	Optional scoring-rule ids to keep active in the returned score.
`scoring.aspectPotencies`	object?	Production defaults	Optional per-aspect strength multipliers, e.g. make sextile weaker or stronger for this request.
`scoring.useNatalHouseFrameOnly`	boolean?	false	The elected chart is the default frame. Set true to ignore temporary election Asc/MC, election-frame sect/hayz, lots, and node-to-angle scoring while retaining natal-house transit placement.
`relocationQuery`	string?	—	Optional current-location search text for relocated angles/houses.
`relocationLatitude`	number?	—	Manual relocation latitude.
`relocationLongitude`	number?	—	Manual relocation longitude.
`secondChart`	object?	—	Optional second chart (another person or an exactly-timed event). When set, the scan runs across the primary chart, this chart, and their composite (midpoint) chart; extra results return in chartResults and the credit cost is multiplied by 3.
`secondChart.kind`	string?	person	"person" \| "event".
`secondChart.label`	string?	—	Display label echoed back on chartResults.
`secondChart.birthDate`*	string	REQ	Second chart date YYYY-MM-DD (birth or event).
`secondChart.birthTime`*	string	REQ	Second chart time HH:MM (24h).
`secondChart.locationQuery`	string?	—	City search text, or supply latitude+longitude.
`secondChart.latitude`	number?	—	Second chart latitude.
`secondChart.longitude`	number?	—	Second chart longitude.
`secondChart.timezone`	string?	—	Timezone override for the second chart's local time.

✦ EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/electional-spellcasting \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "intentId": "career-advancement-promotion",
    "birthDate": "1990-06-15",
    "birthTime": "14:30",
    "locationQuery": "New York, NY",
    "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": [] }
  }
}

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

FIELD	TYPE	DEFAULT	DESCRIPTION
`chartA / chartB`*	object	REQ	Two charts; each needs birthDate (YYYY-MM-DD), birthTime (HH:MM), and locationQuery OR latitude+longitude, plus optional label and timezone.
`houseSystem`	string	P	House system used for overlay cusps.
`orbDegrees`	number	3	Synastry inter-aspect orb (0.5-6). Composite internal aspects use a fixed 4-degree orb.

☉ RESPONSE

{
  "metadata": { "chartALabel": "Jordan", "chartBLabel": "Riley", "creditsRemaining": 9 },
  "relationship": {
    "domains": [
      {
        "id": "marriage_romance",
        "label": "Marriage & romance",
        "score": 7.75,
        "maxScore": 14,
        "percent": 55,
        "band": "promising",
        "evidence": [
          {
            "kind": "synastry_aspect",
            "label": "Jordan Sun trine Riley Moon (orb 2.0°)",
            "points": 4,
            "detail": "Core identity meets emotional nature — the classic marriage signature."
          }
        ],
        "caveats": []
      }
    ],
    "topAspects": [],
    "aspectCounts": { "supportive": 6, "challenging": 3, "charged": 2 }
  },
  "charts": { "a": { "points": {} }, "b": { "points": {} }, "composite": { "points": {} } }
}

The friction_challenges domain is inverted: a high percent 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 up to 2 ranked windows per intent in one flattened, score-sorted list. Use now mode to score one exact election at browser time.

Auth model: 3 free uses per IP per week. After that, the route requires an authenticated app session and charges 1 credit after a successful scan.

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

FIELD	TYPE	DEFAULT	DESCRIPTION
`birthDate`*	string	REQ	Birth date YYYY-MM-DD.
`birthTime`*	string	REQ	Birth time HH:MM (24h).
`scanMode`	"day" \| "now"	"day"	Use day for the rolling 24-hour scan, or now to score exactly browserNowIso.
`startTime`	string?	—	Optional local scan start HH:MM, clipped to the rolling 24-hour range. Must be paired with endTime.
`endTime`	string?	—	Optional local scan end HH:MM, clipped to the rolling 24-hour range. Must be later than startTime.
`locationQuery`	string?	—	Birthplace search, e.g. "Paris, France".
`latitude`	number?	—	Birth latitude (-90..90).
`longitude`	number?	—	Birth longitude (-180..180).
`timezone`	string?	—	Birth timezone override for natal conversion.
`browserNowIso`	string?	—	Optional browser timestamp that anchors the rolling 24-hour scan.
`browserTimezone`	string?	—	Optional browser IANA timezone used to resolve scan labels and clock windows.
`aspects`	string[]?	All 13	Optional transit aspects to calculate for the daily scan.
`asteroidFinder`	boolean	true	Find asteroid discovery contacts at 1 degree conjunction/opposition only; curated ones add a small hard-capped Pass 7 contribution and never create a window.
`fixedStarFinder`	boolean	true	Find fixed-star and galactic-point discovery contacts at 1 degree conjunction/opposition only; curated ones add a small hard-capped Pass 7 contribution and never create a window.
`scoring.enabledPasses`	string[]?	All 7	Optional pass ids to keep active in daily-election scoring.
`scoring.enabledRules`	string[]?	All rule groups	Optional scoring-rule ids to keep active in daily-election scoring.
`scoring.aspectPotencies`	object?	Production defaults	Optional per-aspect strength multipliers for daily-election scoring.
`scoring.useNatalHouseFrameOnly`	boolean?	false	The elected chart is the default frame. Set true to suppress temporary election Asc/MC and related election-frame evidence while retaining natal-house transit placement.
`relocationQuery`	string?	—	Optional current-location search text for relocated angles and houses.
`relocationLatitude`	number?	—	Manual relocation latitude.
`relocationLongitude`	number?	—	Manual relocation longitude.

✦ EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/daily-elections \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-06-15",
    "birthTime": "14:30",
    "locationQuery": "New York, NY",
    "scanMode": "day",
    "browserNowIso": "2026-04-08T08:15:00.000-04:00",
    "browserTimezone": "America/New_York",
    "startTime": "09:00",
    "endTime": "17:00",
    "scoring": { "useNatalHouseFrameOnly": false }
  }'

☉ RESPONSE

{
  "metadata": {
    "locationLabel": "New York, NY, USA",
    "latitude": 40.7128,
    "longitude": -74.006,
    "timezone": "America/New_York",
    "timingTimezone": "America/New_York",
    "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": "America/New_York",
    "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.

REQUEST BODY - JSON

{
  "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 using editable Markdown prompt templates. 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.

Prompt selection: prompts/{domain}-{orientation}-{scope}.md. 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

FIELD	TYPE	DEFAULT	DESCRIPTION
`domain`*	"transits" \| "election" \| "solarReturn" \| "timeline"	REQ	Chooses the transit, election, solar-return, or Timeline prompt family.
`orientation`*	"pragmatic" \| "esoteric"	REQ	Chooses practical action guidance or magical/ritual guidance.
`scope`*	"single" \| "many"	REQ	Chooses single-item or multi-item prompt structure.
`item`	object	—	Required when scope is single. The request keeps the same flat cost.
`items`	object[]	—	Required when scope is many. Direct prompt input is compacted and capped at 96 items; the request keeps the same flat cost.
`context`	object?	—	Optional non-item metadata such as natal data, intent, scan metadata, or user settings.
`question`	string?	—	Optional user-specific question to steer the guidance.
`model`	string?	—	Optional provider-family model override. glm-* applies to Z.ai generation; gemini-* applies if Gemini fallback is used. It does not force provider selection.
`temperature`	number	0.4	Provider sampling temperature from 0 to 2.

EXAMPLE REQUEST

curl -X POST https://your-domain.com/api/v1/ai-guidance \
  -H "Authorization: Bearer sk_tr_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "election",
    "orientation": "esoteric",
    "scope": "many",
    "items": [
      { "peakAtIso": "2026-05-01T10:00:00.000Z", "score": { "total": 18.4 } },
      { "peakAtIso": "2026-05-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

MCP server included for Claude Desktop and other MCP clients. It exposes every public POST /api/v1 route as a tool against the same live REST API.

✦ SETUP

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

Download Claude Desktop Template Get API Key

INSTALL

1. Clone this repository locally and run npm install in the repo root.
2. Download the Claude Desktop template above and open your local MCP config file.
3. Replace /ABSOLUTE/PATH/TO/transits/src/mcp/index.ts with the full absolute path to your local checkout.
4. Set TRANSITS_API_URL to your Electional API base URL and TRANSITS_API_KEY to a live API key from /api-keys.
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 repo root.

WHAT YOU GET

The MCP server currently exposes generate_ai_guidance, expand_aspect_interpretation, calculate_daily_elections, calculate_electional_spellcasting, calculate_eclipse_hits, 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. 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 5 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).