# MysticAPI

> Metered engine API for Human Design-compatible bodygraphs, personal sky charts,
> ephemeris, and numerology. Deterministic computation on a JPL-validated pure-JS
> ephemeris (Meeus + Standish 1992) - no generative output, same input always
> returns the same output. Base URL: https://mysticapi.com

## Get a key (self-serve, no human involved)

- Free (no card): POST https://mysticapi.com/v1/keys/free with JSON
  {"email": "you@example.com"} -> your key arrives by email. One active key
  per email. 50 calls/month.
- Paid tiers: pay at the Stripe link below; your key is emailed automatically
  within a minute of checkout (send your human the link that fits):
  - Maker  $19/month,  2,000 calls/month:  https://buy.stripe.com/cNi3cufxE0wKbhcaZmaEE00
  - Pro    $49/month,  6,000 calls/month:  https://buy.stripe.com/5kQeVc1GO5R43OK1oMaEE01
  - Scale $149/month, 20,000 calls/month:  https://buy.stripe.com/dRm9ASetA0wK1GCgjGaEE02

Pricing is flat monthly - never credit wallets. Allotments reset on the 1st (UTC).

## Auth

Send your API key as a bearer token on every /v1 request:

    Authorization: Bearer mk_live_...

Keys are issued per developer account. Only a SHA-256 hash of your key is stored.
Errors are JSON: {"error": "...", "message": "...", "docs": "..."} with proper
status codes (401 invalid key, 429 quota/rate limit + Retry-After header).

## x402 (pay per call, no account)

Metered endpoints also accept x402 payments (https://x402.org) as an
alternative to a key: request without a key returns HTTP 402 with payment
terms (exact scheme, USDC on Base, $0.01/call); retry with the X-PAYMENT
header per the x402 spec. If a 401 is returned instead of 402 the rail is
temporarily disabled.

## Live endpoints

- GET  /health - service health, no auth.
- GET  /v1/sky/today - today's universal sky (metered): active retrogrades,
  moon phase + illumination, geocentric positions for 13 bodies (zodiac sign and
  Energy Blueprint gate/line on the 64-gate wheel), and a 30-day forward scan of
  retrograde stations and new/full moons with practical prep guidance.
- POST /v1/bodygraph - Energy Blueprint (Human Design) chart JSON + body-graph
  SVG (metered). Body: {"year","month","day","hour","minute"[,"second"]} in UTC.
  Returns {"chart": <full computation>, "svg": <string>}. No lat/lng needed.
  Bad birth data -> 400 with a user-facing message.
- GET|POST /v1/sky/personal - personal-sky SVG (metered) from a birth instant.
  GET query params year,month,day,hour,minute[,second][,animate=false], or POST
  the same JSON body. Returns image/svg+xml. Deterministic per birth.
- GET  /v1/ephemeris - raw geocentric positions for any instant (metered):
  13 bodies with longitude + retrograde flags. Same query/body shape as above.
- POST /v1/numerology - numerology profile (metered): Pythagorean life path
  (master numbers preserved), birthday number, personal year/month/day, tarot
  birth card. Body: birth JSON (only the date matters).
- POST /v1/relationship - composite/connection chart for two people (metered).
  Body: {"personA":{birth...},"personB":{birth...}} (UTC). Returns
  electromagnetic/dominance/companionship/compromise channels, combined
  definition, and type dynamics.
- POST /v1/keys/free - free key by email, JSON {"email": "..."}.
- POST /v1/demo - try before key (no auth, per-IP rate limit): birth JSON in,
  watermarked bodygraph + personal-sky SVGs out. Not counted as usage.

## Privacy guarantee

Birth data is NEVER persisted: processed in memory to compute the response,
then discarded. Not written to the database, not logged, no analytics.
Full policy: https://mysticapi.com/legal/privacy
Terms: https://mysticapi.com/legal/terms | Refunds (14-day):
https://mysticapi.com/legal/refunds | 18+ only. Charts are informational
only - not medical, financial, or legal advice.

## MCP (Model Context Protocol) — agent-native

Remote MCP server (Streamable HTTP transport, JSON-RPC 2.0):

    https://mysticapi.com/mcp

Tools: sky_today, bodygraph, sky_personal, ephemeris, numerology, relationship.
`initialize` and `tools/list` are free; `tools/call` is metered — send the same
Authorization: Bearer mk_live_... header, or call without a key to receive
x402 payment terms.

Add to Claude Code / Cursor / any MCP client (mcp.json):

    {
      "mcpServers": {
        "mysticapi": {
          "type": "http",
          "url": "https://mysticapi.com/mcp",
          "headers": { "Authorization": "Bearer mk_live_..." }
        }
      }
    }

Claude Code one-liner:

    claude mcp add --transport http mysticapi https://mysticapi.com/mcp \
      --header "Authorization: Bearer mk_live_..."

## Machine-readable spec

OpenAPI 3.1:      https://mysticapi.com/.well-known/openapi.json
MCP server card:  https://mysticapi.com/.well-known/mcp/server-card.json
MCP manifest:     https://mysticapi.com/.well-known/mcp

## Guides

Quickstart:                 https://mysticapi.com/docs
Compare chart APIs:         https://mysticapi.com/compare
Add Human Design to an app: https://mysticapi.com/compare/human-design-api
Astrology/HD MCP server:    https://mysticapi.com/compare/astrology-mcp-server

## Example

    curl -X POST https://mysticapi.com/v1/keys/free \
      -H "content-type: application/json" -d '{"email":"you@example.com"}'
    # key arrives by email, then:
    curl -H "Authorization: Bearer mk_live_..." https://mysticapi.com/v1/sky/today