API DOCS

♄ AUTHENTICATION & BILLING

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

Authorization: Bearer sk_tr_your_key_here

/api/v1/transits: 1 credit per day scanned, plus 1 credit when transitToTransit: true. Credits exposed via x-credits-remaining.

/api/v1/electional-spellcasting: 1 credit per 30 days scanned per intent. Transit-to-transit data is always calculated, but its scoring contribution can now be disabled per request or via saved account settings.

/api/v1/daily-elections: 3 free uses per IP per week, then 1 credit after a successful scan. This route uses the app session flow rather than 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/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/ai-guidance: 3 credits per guidance question or narrative follow-up, 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.

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

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/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

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

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

✦ AVAILABLE VALUES

☉ 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

POST/api/v1/electional-spellcasting

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

Credit model: 1 CREDIT PER 60 DAYS scanned. 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. 35 live rule layers across 6 ordered passes, with transit-to-natal weighting kept above transit-to-transit refinement.

☽ REQUIRED FIELDS

✦ 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": true,
      "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"
      }
    }
  ]
}

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 as context in discoveryHits/discoveryHitInsights and are not included in election scores.

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

✦ 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": true }
  }'

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

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 Gemini guidance from transit hits, election windows, or solar-return dossiers using editable Markdown prompt templates.

Credit model: 1 CREDIT PER ITEM in item or items. The route reserves credits before sending data to Gemini, saves successful guidance before returning it, and refunds credits if generation or auto-save fails. Invalid requests, missing Gemini config, and insufficient-credit responses do not call Gemini or consume credits.

Prompt selection: prompts/{domain}-{orientation}-{scope}.md, where domain is transits, election, or solarReturn, orientation is pragmatic or esoteric, and scope is single or many.

REQUEST BODY - JSON

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": "gemini-3-pro-preview",
    "promptTemplate": "election-esoteric-many.md"
  }
}

⚷ MCP SERVER

MCP server included for Claude Desktop and other MCP clients. It exposes transit, electional, solar-return, paid Timeline full-report, and Vedic Chart tools 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"
      }
    }
  }
}

INSTALL

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

WHAT YOU GET

The MCP server currently exposes calculate_transits, calculate_electional_spellcasting, calculate_solar_return, calculate_timeline_full_report, calculate_vedic_chart. All tools call the same live REST API documented on this page; the Timeline full-report tool uses /api/v1/timeline/full and follows its 3 credits successful-report charge, while calculate_vedic_chart uses /api/v1/vedic-chart/full and follows its 3 credits successful-report charge.