The Occult API

Spirit lookups, divination casts, graph traversal, and doctrinal analysis — all through a clean REST API. Free tier with no credit card. Interactive docs. MCP server for AI agent integration.

Get Your API Key Quickstart Guide →

Live API Console

Try it right now. No API key needed for the free tier. Edit any request and hit Send.

Stars Engine API Console

# Type a curl command above and hit Send to call the API. # Try one of the presets below, or craft your own request.

28 Endpoints

Full list of what's available. Every endpoint returns JSON. Every response is documented.

GET /api/stars/esoteric/spirits

POST /api/stars/divination/cast

GET /api/stars/graph/brief/{system}

GET /api/stars/graph/suggest/{concept}

GET /api/stars/graph/rosetta

GET /api/stars/graph/search

GET /api/stars/research/doctrinal-drift

GET /api/stars/timing/planetary_hours

POST /api/stars/chaos/sigilize

GET /api/stars/health

POST /api/auth/signup

POST /api/auth/login

+ 16 additional endpoints for charts, synastry, quiz scoring, visuals, and account management. Full reference →

Why Developers Choose Stars

📡

28 REST Endpoints

Spirit lookups, divination casts, graph traversal, doctrinal analysis, chart computation, synastry, and more. Clean JSON responses with consistent error formats. Every endpoint documented in OpenAPI 3.1.

🤖

MCP Server

Integrate Stars Engine directly into AI agents via the Model Context Protocol. 6 tools: spirit lookup, graph brief, graph rosetta, chart compute, geomancy cast, and planetary hours. SSE transport. JSON-RPC 2.0 messages. Practitioner tier and above.

🔀

Graph Rosetta

Translate any concept across 113+ traditions. "Mars" → Mangal (Vedic), Geburah (Kabbalah), Iron (Alchemy), Pele (Hawaiian). Linguistic equivalents, doctrinal correspondences, and empirical co-occurrence data — all through a single GET.

🗳️

Geomancy Cast

POST a seed string, get back a full geomantic Shield Chart: Mothers, Daughters, Nephews, Witnesses, and Judge. Use for divination features in games, interactive fiction, or ritual tools.

🧪

Doctrinal Drift Analysis

Measure how a concept changes across traditions and time periods. Compare Renaissance Hermetic correspondences against modern New Age tables. Quantify semantic shift with cosine distance over embedded concept vectors.

🎓

Free Tier, Real Value

30 req/min on the free tier — enough to prototype and explore. Spirit lookups and planetary hours don't even require an API key. Upgrade when you're ready for production traffic. No credit card to get started.

Start Building in 30 Seconds

# No API key required for spirit lookups
curl "https://stars.madmanwithabox.org/api/stars/esoteric/spirits?sign=Aries°ree=15"

# With an API key (Practitioner tier):
curl -H "X-API-Key: $STARS_API_KEY" \
  "https://stars.madmanwithabox.org/api/stars/graph/rosetta?concept=Mars&target=golden_dawn"

import requests

# Spirit lookup — no API key needed
r = requests.get("https://stars.madmanwithabox.org/api/stars/esoteric/spirits",
                 params={"sign": "Aries", "degree": 15})
spirits = r.json()
print(spirits["goetic"]["name"])  # → Marbas

# Graph rosetta — with API key
r = requests.get("https://stars.madmanwithabox.org/api/stars/graph/rosetta",
                 params={"concept": "Mars", "target": "golden_dawn"},
                 headers={"X-API-Key": "sk-..."})
print(r.json()["doctrinal"])

// Spirit lookup — no API key needed
const spirits = await fetch(
  "https://stars.madmanwithabox.org/api/stars/esoteric/spirits?sign=Aries°ree=15"
).then(r => r.json());
console.log(spirits.goetic.name);   // → "Marbas"
console.log(spirits.shem.name);     // → "Vehuel"

// Graph rosetta — with API key
const data = await fetch(
  "https://stars.madmanwithabox.org/api/stars/graph/rosetta?concept=Mars&target=golden_dawn",
  { headers: { "X-API-Key": "sk-..." } }
).then(r => r.json());

Runs on Our Hardware. Not Big Tech's.

The API you're calling isn't hosted on AWS, Google Cloud, or Azure. Chart computation runs on a dedicated server in Texas. The public API frontend runs on independent infrastructure in Germany. No venture capital. No ad-tech executives. No data brokers. Your requests never touch a cloud provider that might log, analyze, or resell them.

🏠

Self-Hosted Compute

Charts are calculated on hardware we physically own. The JPL ephemeris (120 MB, sub-arcsecond precision) never leaves our server. Your birth data goes to our machine, not a cloud API.

🔒

No Training, No Selling

We don't train models on your requests. We don't sell your data. We don't log your API calls for analytics. The free tier is genuinely free — not a data harvesting operation dressed as an API.

💰

Fair Pricing, No Surprises

Free tier: 30 req/min — enough to prototype. Enthusiast: $12/mo. Practitioner: $59/mo with API keys + MCP. Studio: $199/mo for production. No "contact sales." No "enterprise pricing." Just an API.

An API for the esoteric — built like you'd build it.

Clean JSON. Interactive docs. No SOAP. No XML. No "enterprise pricing" that requires a sales call. Just a REST API that returns real data about real occult systems — running on infrastructure we own.

Get Your API Key

Invite-only beta. Free tier: 30 req/min, no credit card. Your data isn't the product — your subscription is.