API DOCS

♄ AUTHENTICATION & BILLING

/api/v1/transits, /api/v1/electional-spellcasting, 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 60 scan days, doubled when transitToTransit: true. Credits exposed via x-credits-remaining.

/api/v1/electional-spellcasting: 1 credit per 60 scan days. 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/ai-guidance: 1 credit per transit or election window passed to Gemini. Prompt templates live in prompts/*.md.

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": 180,
    "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. 25 live rule layers across 5 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": 120,
    "strictness": "standard",
    "scoring": {
      "enabledPasses": ["pass1Baseline", "pass3IntentFit", "pass4NatalCompatibility"],
      "enabledRules": ["moon_phase", "primary_significator_hits", "natal_anchor_hits"]
    }
  }'

☉ RESPONSE

{
  "metadata": {
    "scanStartDate": "2026-01-01",
    "scanEndDate": "2026-04-30",
    "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 election house 10" }
          ]
        }
      ]
    }
  ]
}

Window rationale may include advanced diagnostics already active in production, including natal target condition, return windows, true void-of-course, Via Combusta, besiegement, lots, antiscia, fixed-star contacts, and nodal or translation/perfection notes when present.

POST/api/v1/daily-elections

Scan all 72 intents across the active local day and return up to 2 ranked windows per intent in one flattened, score-sorted list.

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 local day. They do not filter a full-day result set after the fact.

☿ 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",
    "browserNowIso": "2026-04-08T08:15:00.000-04:00",
    "browserTimezone": "America/New_York",
    "startTime": "09:00",
    "endTime": "17:00"
  }'

☉ 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",
    "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 election house 11" }
          ]
        }
      ]
    }
  ]
}

POST/api/v1/ai-guidance

Generate Gemini guidance from transit hits or election windows using editable Markdown prompt templates.

Credit model: 1 CREDIT PER ITEM in item or items. The route reserves credits before sending data to Gemini and refunds them if generation 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 or election, 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": 2,
    "creditsRemaining": 7,
    "model": "gemini-3-pro-preview",
    "promptTemplate": "election-esoteric-many.md"
  }
}

⚷ MCP SERVER

MCP server included for Claude Desktop and other MCP clients. Exposes calculate_transits and calculate_electional_spellcasting tools.

✦ 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 and calculate_electional_spellcasting. Both tools call the same live REST API documented on this page.