API Quickstart — Stars Engine

Your First Call — Spirit Lookup

Every degree of the zodiac is watched by specific spirits. Here's how to find which Goetic spirit, Shem angel, Egyptian decan deity, and Enochian Aethyr governs any degree. No API key required for spirit lookups.

curl "https://stars.madmanwithabox.org/api/stars/esoteric/spirits?sign=Aries°ree=15"

import requests

response = requests.get(
    "https://stars.madmanwithabox.org/api/stars/esoteric/spirits",
    params={"sign": "Aries", "degree": 15}
)
data = response.json()

for tradition, info in data.items():
    print(f"{tradition}: {info.get('name', '?')}")

const res = await fetch(
  "https://stars.madmanwithabox.org/api/stars/esoteric/spirits?sign=Aries°ree=15"
);
const data = await res.json();

// { goetic: { name, rank, office, ... },
//   shem:   { name, verse, choir, ... },
//   egyptian_decan: { name, domain, body_part, ... },
//   enochian: { aethyr, name, governor, ... } }
console.log(data.goetic.name);

Try the interactive demo →

What Else Can You Call?

Every endpoint is available without an API key on the free tier. Higher tiers get more requests per minute, batch access, and MCP server access.

GET /api/stars/timing/planetary_hours Planetary hours for any date and location

curl "https://stars.madmanwithabox.org/api/stars/timing/planetary_hours?date=2026-07-29&lat=30&lon=-95"

resp = requests.get(
    "https://stars.madmanwithabox.org/api/stars/timing/planetary_hours",
    params={"date": "2026-07-29", "lat": 30, "lon": -95}
)
hours = resp.json()
# → { sunrise, sunset, hours: [{planet, start, end}, ...], current_hour: {...} }

const h = await fetch(
  "https://stars.madmanwithabox.org/api/stars/timing/planetary_hours?date=2026-07-29&lat=30&lon=-95"
).then(r => r.json());
console.log(h.day_ruler);              // e.g. "Mercury"
	console.log(h.daylight_hours[0].planet);  // first hour's planet

POST /api/stars/divination/cast Geomancy cast from a seed or random

curl -X POST "https://stars.madmanwithabox.org/api/stars/divination/cast" \
  -H "Content-Type: application/json" \
  -d '{"system":"geomancy","seed":"what does this day hold"}'

resp = requests.post(
    "https://stars.madmanwithabox.org/api/stars/divination/cast",
    json={"system": "geomancy", "seed": "what does this day hold"}
)
cast = resp.json()
# → { mothers, daughters, nephews, judge, witnesses, shield_chart }

const cast = await fetch(
  "https://stars.madmanwithabox.org/api/stars/divination/cast",
  { method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({system: "geomancy", seed: "what does this day hold"})
  }
).then(r => r.json());
console.log(cast.judge);  // e.g. "Populus"

GET /api/stars/graph/rosetta Translate a concept across traditions

curl "https://stars.madmanwithabox.org/api/stars/graph/rosetta?concept=Mars&target=golden_dawn"

resp = requests.get(
    "https://stars.madmanwithabox.org/api/stars/graph/rosetta",
    params={"concept": "Mars", "target": "golden_dawn"}
)
translation = resp.json()
# → { linguistic: {...}, doctrinal: [...], empirical: [...] }

const t = await fetch(
  "https://stars.madmanwithabox.org/api/stars/graph/rosetta?concept=Mars&target=golden_dawn"
).then(r => r.json());
console.log(t.doctrinal);  // Mars → Geburah, Iron, Tuesday, ...

POST /api/stars/chaos/sigilize Generate a sigil from an intent statement

curl -X POST "https://stars.madmanwithabox.org/api/stars/chaos/sigilize" \
  -H "Content-Type: application/json" \
  -d '{"intent":"I WILL COMPLETE THE WORK","method":"spare"}'

resp = requests.post(
    "https://stars.madmanwithabox.org/api/stars/chaos/sigilize",
    json={"intent": "I WILL COMPLETE THE WORK", "method": "spare"}
)
sigil = resp.json()
# → { sigil_svg, reduced_phrase, method }

const s = await fetch(
  "https://stars.madmanwithabox.org/api/stars/chaos/sigilize",
  { method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({intent: "I WILL COMPLETE THE WORK", method: "spare"})
  }
).then(r => r.json());
// s.sigil_svg contains the generated sigil

The Occult API

Your First Call — Spirit Lookup

What Else Can You Call?

Rate Limits & Tiers