API Reference

AstralAPI

A clean REST API for spiritual content — twelve modules, one base URL, one auth scheme. Register, create an app, copy your token, and use it as a Bearer in your requests.

Base URL & response shape

GET https://staging.astralapi.dev/api/v1/...
Authorization: Bearer <token>

// successful responses
{ "data": ... }

// errors
{ "error": "App token required" }

Zodiac

GET/api/v1/zodiac/signs

List all twelve zodiac signs with element, modality, ruling planet, and date range.

Authentication

App token

Response example

{
  "data": [
    {
      "id": 1,
      "name": "Aries",
      "slug": "aries",
      "symbol": "♈",
      "start_date": "03-21",
      "end_date": "04-19",
      "element": "Fire",
      "quality": "Cardinal",
      "ruling_planet": "Mars"
    },
    {
      "id": 2,
      "name": "Taurus",
      "slug": "taurus",
      "symbol": "♉",
      "start_date": "04-20",
      "end_date": "05-20",
      "element": "Earth",
      "quality": "Fixed",
      "ruling_planet": "Venus"
    }
  ]
}

GET/api/v1/zodiac/horoscope/{sign}

Daily horoscope for the given sign, generated fresh each day.

Authentication

App token

Parameters

Name	Type	Required	Description
`sign`	string	required	Zodiac sign slug, e.g. aries, leo, scorpio

Response example

{
  "data": {
    "sign": "leo",
    "date": "2026-05-14",
    "reading": "The spotlight finds you naturally today. Trust what you know and say it without softening the edges."
  }
}

Tarot

GET/api/v1/tarot/cards

List all 78 tarot cards with name, arcana, suit, and numerological value.

Authentication

App token

Response example

{
  "data": [
    {
      "id": 1,
      "name": "The Fool",
      "arcana": "major",
      "suit": null,
      "value": 0
    },
    {
      "id": 2,
      "name": "The Magician",
      "arcana": "major",
      "suit": null,
      "value": 1
    },
    {
      "id": 23,
      "name": "Ace of Wands",
      "arcana": "minor",
      "suit": "wands",
      "value": 1
    }
  ]
}

GET/api/v1/tarot/reading

AI-generated reading for a pre-drawn set of cards. Fetch /tarot/cards first, draw 1 or 3, then pass them here as a JSON-encoded query param.

Authentication

App token

Parameters

Name	Type	Required	Description
`sign`	string	required	Zodiac sign of the querent, e.g. gemini
`cards`	string	required	JSON-encoded array of card objects from /tarot/cards, e.g. [{"id":1,"name":"The Fool"}]
`spread`	string	optional	one \| three (default: three)
`area`	string	optional	Reading focus, e.g. love, career, general
`name`	string	optional	Querent's name for a personalised reading

Response example

{
  "data": {
    "sign": "gemini",
    "spread": "three",
    "cards": [
      {
        "position": "past",
        "card": "The Hermit",
        "reading": "A period of solitude shaped who you are now."
      },
      {
        "position": "present",
        "card": "The Star",
        "reading": "Clarity follows the chaos. Trust the quiet pull forward."
      },
      {
        "position": "future",
        "card": "Judgement",
        "reading": "A decisive moment approaches. Answer the call honestly."
      }
    ],
    "summary": "You have been learning in solitude. The stars confirm this season asks for action."
  }
}

Numerology

GET/api/v1/numerology

Compute a numerology profile from a birthdate and full name.

Authentication

App token

Parameters

Name	Type	Required	Description
`birthdate`	string	required	Date of birth in YYYY-MM-DD format
`name`	string	required	Full name of the person

Response example

{
  "data": {
    "lifepath": 7,
    "expression": 5,
    "soul_urge": 3,
    "personality": 2,
    "summary": "The seeker. Introspective and drawn to hidden truths."
  }
}

Natal Chart

GET/api/v1/natal

Compute an astrological natal chart from birth data.

Authentication

App token

Parameters

Name	Type	Required	Description
`birthdate`	string	required	Date of birth in YYYY-MM-DD format
`time_of_birth`	string	required	Time of birth in HH:MM (24h)
`location`	string	required	Birth city and country, e.g. Santiago, Chile

Response example

{
  "data": {
    "sun": "leo",
    "moon": "pisces",
    "ascendant": "scorpio",
    "houses": [
      {
        "house": 1,
        "sign": "scorpio"
      },
      {
        "house": 2,
        "sign": "sagittarius"
      }
    ],
    "planets": [
      {
        "planet": "sun",
        "sign": "leo",
        "house": 10,
        "degree": 12.3
      },
      {
        "planet": "moon",
        "sign": "pisces",
        "house": 5,
        "degree": 7.8
      }
    ]
  }
}

Compatibility

GET/api/v1/compatibility/{sign1}/{sign2}

Score astrological compatibility between two zodiac signs.

Authentication

App token

Parameters

Name	Type	Required	Description
`sign1`	string	required	First zodiac sign slug, e.g. aries
`sign2`	string	required	Second zodiac sign slug, e.g. libra

Response example

{
  "data": {
    "sign1": "aries",
    "sign2": "libra",
    "score": 84,
    "love": 88,
    "friendship": 76,
    "summary": "Magnetic tension balanced by mutual respect."
  }
}

Astrology

GET/api/v1/astro/moon

Current moon phase, illumination percentage, and sign.

Authentication

App token

Response example

{
  "data": {
    "phase": "waxing gibbous",
    "illumination": 0.78,
    "sign": "scorpio"
  }
}

GET/api/v1/astro/moon/calendar

Moon phase calendar for a given month and year.

Authentication

App token

Parameters

Name	Type	Required	Description
`month`	integer	optional	Month 1–12 (default: current month)
`year`	integer	optional	Full year, e.g. 2026 (default: current year)

Response example

{
  "data": [
    {
      "date": "2026-05-01",
      "phase": "new moon",
      "illumination": 0.01
    },
    {
      "date": "2026-05-08",
      "phase": "first quarter",
      "illumination": 0.50
    },
    {
      "date": "2026-05-12",
      "phase": "full moon",
      "illumination": 1.00
    },
    {
      "date": "2026-05-20",
      "phase": "last quarter",
      "illumination": 0.50
    }
  ]
}

GET/api/v1/astro/planets

Current positions and signs for the main planets.

Authentication

App token

Response example

{
  "data": [
    {
      "planet": "sun",
      "sign": "taurus",
      "degree": 23.4,
      "retrograde": false
    },
    {
      "planet": "mercury",
      "sign": "aries",
      "degree": 8.1,
      "retrograde": false
    },
    {
      "planet": "venus",
      "sign": "gemini",
      "degree": 15.7,
      "retrograde": false
    }
  ]
}

GET/api/v1/astro/events

Notable astrological events (full moons, retrogrades, ingresses) for a given month.

Authentication

App token

Parameters

Name	Type	Required	Description
`month`	integer	optional	Month 1–12 (default: current month)
`year`	integer	optional	Full year, e.g. 2026 (default: current year)

Response example

{
  "data": [
    {
      "date": "2026-05-12",
      "type": "full moon",
      "description": "Full moon in Scorpio"
    },
    {
      "date": "2026-05-14",
      "type": "mercury retrograde",
      "description": "Mercury stations retrograde in Gemini"
    }
  ]
}

Rituals

GET/api/v1/rituals

List all rituals from the database.

Authentication

App token

Response example

{
  "data": [
    {
      "id": "rit_full_moon_001",
      "title": "Full Moon Release",
      "duration": 25,
      "focus": "release"
    },
    {
      "id": "rit_morning_001",
      "title": "Morning Intention",
      "duration": 10,
      "focus": "intention"
    }
  ]
}

GET/api/v1/rituals/{id}

Get a full ritual including its ordered steps.

Authentication

App token

Parameters

Name	Type	Required	Description
`id`	string	required	Ritual ID, e.g. rit_full_moon_001

Response example

{
  "data": {
    "id": "rit_full_moon_001",
    "title": "Full Moon Release",
    "duration": 25,
    "focus": "release",
    "energy": "release",
    "moonPhase": "full",
    "steps": [
      {
        "order": 1,
        "title": "Set your space",
        "description": "Clear the room and light a candle."
      },
      {
        "order": 2,
        "title": "Write and release",
        "description": "Write what you want to release, then burn the paper safely."
      },
      {
        "order": 3,
        "title": "Close the circle",
        "description": "Breathe deeply and state your release aloud."
      }
    ]
  }
}

Crystals

GET/api/v1/crystals

List all crystals from the database.

Authentication

App token

Response example

{
  "data": [
    {
      "slug": "amethyst",
      "name": "Amethyst",
      "element": "Air",
      "color": "#9B6BD0"
    },
    {
      "slug": "rose-quartz",
      "name": "Rose Quartz",
      "element": "Water",
      "color": "#F4A7B9"
    }
  ]
}

GET/api/v1/crystals/{slug}

Get a crystal by slug, including full description and tagline.

Authentication

App token

Parameters

Name	Type	Required	Description
`slug`	string	required	Crystal slug, e.g. amethyst

Response example

{
  "data": {
    "slug": "amethyst",
    "name": "Amethyst",
    "element": "Air",
    "color": "#9B6BD0",
    "tagline": "Calm the mind, open the third eye.",
    "description": "A stone of calm and spiritual clarity, beloved for meditation."
  }
}

Playlists

GET/api/v1/playlists

List all curated playlists from the database.

Authentication

App token

Response example

{
  "data": [
    {
      "slug": "morning-motivation",
      "title": "Morning Motivation",
      "category": "morning"
    },
    {
      "slug": "deep-focus",
      "title": "Deep Focus",
      "category": "focus"
    }
  ]
}

GET/api/v1/playlists/{slug}

Get a playlist by slug, including Spotify URL and embed URL.

Authentication

App token

Parameters

Name	Type	Required	Description
`slug`	string	required	Playlist slug, e.g. morning-motivation

Response example

{
  "data": {
    "slug": "morning-motivation",
    "title": "Morning Motivation",
    "category": "morning",
    "description": "Start your day with clarity and intention.",
    "spotify_url": "https://open.spotify.com/playlist/37i9dQZF1DX0UrRvztWcAU",
    "embed_url": "https://open.spotify.com/embed/playlist/37i9dQZF1DX0UrRvztWcAU"
  }
}

Names

POST/api/v1/names

Analyse a name and store the result. Returns meaning, origin, and vibrational profile.

Authentication

App token

Parameters

Name	Type	Required	Description
`name`	string	required	Given name to analyse (JSON request body)

Response example

{
  "data": {
    "name": "Luna",
    "origin": "Latin",
    "meaning": "moon",
    "vibration": "intuitive, reflective, cyclical"
  }
}

GET/api/v1/names

List previously analysed names, paginated.

Authentication

App token

Parameters

Name	Type	Required	Description
`page`	integer	optional	Page number (default: 1)
`limit`	integer	optional	Results per page (default: 20)

Response example

{
  "data": [
    {
      "name": "Luna",
      "origin": "Latin",
      "meaning": "moon"
    },
    {
      "name": "Sol",
      "origin": "Latin",
      "meaning": "sun"
    }
  ],
  "page": 1,
  "total": 12
}

Personality

GET/api/v1/personality

Derive a personality archetype from astrological and numerological inputs. All params are optional — provide as many as available for a richer result.

Authentication

App token

Parameters

Name	Type	Required	Description
`birthdate`	string	optional	YYYY-MM-DD
`time_of_birth`	string	optional	HH:MM (24h)
`location`	string	optional	City and country, e.g. Santiago, Chile
`name`	string	optional	Given name for numerological input

Response example

{
  "data": {
    "archetype": "The Lantern",
    "traits": ["introspective", "guiding", "luminous"],
    "summary": "You illuminate paths for others while navigating your own."
  }
}

Quotes

GET/api/v1/quotes

Today's daily spiritual quote.

Authentication

App token

Response example

{
  "data": {
    "quote": "Soften the grip. Stay.",
    "author": "—"
  }
}

Geocoding

GET/api/v1/geocoding/cities

Search cities by name. Use this to resolve birth locations before calling /natal or /personality.

Authentication

App token

Parameters

Name	Type	Required	Description
`q`	string	required	City name to search, e.g. Santiago

Response example

{
  "data": [
    {
      "name": "Santiago",
      "country": "Chile",
      "lat": -33.4569,
      "lng": -70.6483
    },
    {
      "name": "Santiago de Compostela",
      "country": "Spain",
      "lat": 42.8782,
      "lng": -8.5448
    }
  ]
}

API Reference

AstralAPI

A clean REST API for spiritual content — twelve modules, one base URL, one auth scheme. Register, create an app, copy your token, and use it as a Bearer in your requests.

Base URL & response shape

GET https://staging.astralapi.dev/api/v1/...
Authorization: Bearer <token>

// successful responses
{ "data": ... }

// errors
{ "error": "App token required" }

Zodiac

GET/api/v1/zodiac/signs

List all twelve zodiac signs with element, modality, ruling planet, and date range.

Authentication

App token

Response example

{
  "data": [
    {
      "id": 1,
      "name": "Aries",
      "slug": "aries",
      "symbol": "♈",
      "start_date": "03-21",
      "end_date": "04-19",
      "element": "Fire",
      "quality": "Cardinal",
      "ruling_planet": "Mars"
    },
    {
      "id": 2,
      "name": "Taurus",
      "slug": "taurus",
      "symbol": "♉",
      "start_date": "04-20",
      "end_date": "05-20",
      "element": "Earth",
      "quality": "Fixed",
      "ruling_planet": "Venus"
    }
  ]
}

GET/api/v1/zodiac/horoscope/{sign}

Daily horoscope for the given sign, generated fresh each day.

Authentication

App token

Parameters

Name	Type	Required	Description
`sign`	string	required	Zodiac sign slug, e.g. aries, leo, scorpio

Response example

{
  "data": {
    "sign": "leo",
    "date": "2026-05-14",
    "reading": "The spotlight finds you naturally today. Trust what you know and say it without softening the edges."
  }
}

Tarot

GET/api/v1/tarot/cards

List all 78 tarot cards with name, arcana, suit, and numerological value.

Authentication

App token

Response example

{
  "data": [
    {
      "id": 1,
      "name": "The Fool",
      "arcana": "major",
      "suit": null,
      "value": 0
    },
    {
      "id": 2,
      "name": "The Magician",
      "arcana": "major",
      "suit": null,
      "value": 1
    },
    {
      "id": 23,
      "name": "Ace of Wands",
      "arcana": "minor",
      "suit": "wands",
      "value": 1
    }
  ]
}

GET/api/v1/tarot/reading

AI-generated reading for a pre-drawn set of cards. Fetch /tarot/cards first, draw 1 or 3, then pass them here as a JSON-encoded query param.

Authentication

App token

Parameters

Name	Type	Required	Description
`sign`	string	required	Zodiac sign of the querent, e.g. gemini
`cards`	string	required	JSON-encoded array of card objects from /tarot/cards, e.g. [{"id":1,"name":"The Fool"}]
`spread`	string	optional	one \| three (default: three)
`area`	string	optional	Reading focus, e.g. love, career, general
`name`	string	optional	Querent's name for a personalised reading

Response example

{
  "data": {
    "sign": "gemini",
    "spread": "three",
    "cards": [
      {
        "position": "past",
        "card": "The Hermit",
        "reading": "A period of solitude shaped who you are now."
      },
      {
        "position": "present",
        "card": "The Star",
        "reading": "Clarity follows the chaos. Trust the quiet pull forward."
      },
      {
        "position": "future",
        "card": "Judgement",
        "reading": "A decisive moment approaches. Answer the call honestly."
      }
    ],
    "summary": "You have been learning in solitude. The stars confirm this season asks for action."
  }
}

Numerology

GET/api/v1/numerology

Compute a numerology profile from a birthdate and full name.

Authentication

App token

Parameters

Name	Type	Required	Description
`birthdate`	string	required	Date of birth in YYYY-MM-DD format
`name`	string	required	Full name of the person

Response example

{
  "data": {
    "lifepath": 7,
    "expression": 5,
    "soul_urge": 3,
    "personality": 2,
    "summary": "The seeker. Introspective and drawn to hidden truths."
  }
}

Natal Chart

GET/api/v1/natal

Compute an astrological natal chart from birth data.

Authentication

App token

Parameters

Name	Type	Required	Description
`birthdate`	string	required	Date of birth in YYYY-MM-DD format
`time_of_birth`	string	required	Time of birth in HH:MM (24h)
`location`	string	required	Birth city and country, e.g. Santiago, Chile

Response example

{
  "data": {
    "sun": "leo",
    "moon": "pisces",
    "ascendant": "scorpio",
    "houses": [
      {
        "house": 1,
        "sign": "scorpio"
      },
      {
        "house": 2,
        "sign": "sagittarius"
      }
    ],
    "planets": [
      {
        "planet": "sun",
        "sign": "leo",
        "house": 10,
        "degree": 12.3
      },
      {
        "planet": "moon",
        "sign": "pisces",
        "house": 5,
        "degree": 7.8
      }
    ]
  }
}

Compatibility

GET/api/v1/compatibility/{sign1}/{sign2}

Score astrological compatibility between two zodiac signs.

Authentication

App token

Parameters

Name	Type	Required	Description
`sign1`	string	required	First zodiac sign slug, e.g. aries
`sign2`	string	required	Second zodiac sign slug, e.g. libra

Response example

{
  "data": {
    "sign1": "aries",
    "sign2": "libra",
    "score": 84,
    "love": 88,
    "friendship": 76,
    "summary": "Magnetic tension balanced by mutual respect."
  }
}

Astrology

GET/api/v1/astro/moon

Current moon phase, illumination percentage, and sign.

Authentication

App token

Response example

{
  "data": {
    "phase": "waxing gibbous",
    "illumination": 0.78,
    "sign": "scorpio"
  }
}

GET/api/v1/astro/moon/calendar

Moon phase calendar for a given month and year.

Authentication

App token

Parameters

Name	Type	Required	Description
`month`	integer	optional	Month 1–12 (default: current month)
`year`	integer	optional	Full year, e.g. 2026 (default: current year)

Response example

{
  "data": [
    {
      "date": "2026-05-01",
      "phase": "new moon",
      "illumination": 0.01
    },
    {
      "date": "2026-05-08",
      "phase": "first quarter",
      "illumination": 0.50
    },
    {
      "date": "2026-05-12",
      "phase": "full moon",
      "illumination": 1.00
    },
    {
      "date": "2026-05-20",
      "phase": "last quarter",
      "illumination": 0.50
    }
  ]
}

GET/api/v1/astro/planets

Current positions and signs for the main planets.

Authentication

App token

Response example

{
  "data": [
    {
      "planet": "sun",
      "sign": "taurus",
      "degree": 23.4,
      "retrograde": false
    },
    {
      "planet": "mercury",
      "sign": "aries",
      "degree": 8.1,
      "retrograde": false
    },
    {
      "planet": "venus",
      "sign": "gemini",
      "degree": 15.7,
      "retrograde": false
    }
  ]
}

GET/api/v1/astro/events

Notable astrological events (full moons, retrogrades, ingresses) for a given month.

Authentication

App token

Parameters

Name	Type	Required	Description
`month`	integer	optional	Month 1–12 (default: current month)
`year`	integer	optional	Full year, e.g. 2026 (default: current year)

Response example

{
  "data": [
    {
      "date": "2026-05-12",
      "type": "full moon",
      "description": "Full moon in Scorpio"
    },
    {
      "date": "2026-05-14",
      "type": "mercury retrograde",
      "description": "Mercury stations retrograde in Gemini"
    }
  ]
}

Rituals

GET/api/v1/rituals

List all rituals from the database.

Authentication

App token

Response example

{
  "data": [
    {
      "id": "rit_full_moon_001",
      "title": "Full Moon Release",
      "duration": 25,
      "focus": "release"
    },
    {
      "id": "rit_morning_001",
      "title": "Morning Intention",
      "duration": 10,
      "focus": "intention"
    }
  ]
}

GET/api/v1/rituals/{id}

Get a full ritual including its ordered steps.

Authentication

App token

Parameters

Name	Type	Required	Description
`id`	string	required	Ritual ID, e.g. rit_full_moon_001

Response example

{
  "data": {
    "id": "rit_full_moon_001",
    "title": "Full Moon Release",
    "duration": 25,
    "focus": "release",
    "energy": "release",
    "moonPhase": "full",
    "steps": [
      {
        "order": 1,
        "title": "Set your space",
        "description": "Clear the room and light a candle."
      },
      {
        "order": 2,
        "title": "Write and release",
        "description": "Write what you want to release, then burn the paper safely."
      },
      {
        "order": 3,
        "title": "Close the circle",
        "description": "Breathe deeply and state your release aloud."
      }
    ]
  }
}

Crystals

GET/api/v1/crystals

List all crystals from the database.

Authentication

App token

Response example

{
  "data": [
    {
      "slug": "amethyst",
      "name": "Amethyst",
      "element": "Air",
      "color": "#9B6BD0"
    },
    {
      "slug": "rose-quartz",
      "name": "Rose Quartz",
      "element": "Water",
      "color": "#F4A7B9"
    }
  ]
}

GET/api/v1/crystals/{slug}

Get a crystal by slug, including full description and tagline.

Authentication

App token

Parameters

Name	Type	Required	Description
`slug`	string	required	Crystal slug, e.g. amethyst

Response example

{
  "data": {
    "slug": "amethyst",
    "name": "Amethyst",
    "element": "Air",
    "color": "#9B6BD0",
    "tagline": "Calm the mind, open the third eye.",
    "description": "A stone of calm and spiritual clarity, beloved for meditation."
  }
}

Playlists

GET/api/v1/playlists

List all curated playlists from the database.

Authentication

App token

Response example

{
  "data": [
    {
      "slug": "morning-motivation",
      "title": "Morning Motivation",
      "category": "morning"
    },
    {
      "slug": "deep-focus",
      "title": "Deep Focus",
      "category": "focus"
    }
  ]
}

GET/api/v1/playlists/{slug}

Get a playlist by slug, including Spotify URL and embed URL.

Authentication

App token

Parameters

Name	Type	Required	Description
`slug`	string	required	Playlist slug, e.g. morning-motivation

Response example

{
  "data": {
    "slug": "morning-motivation",
    "title": "Morning Motivation",
    "category": "morning",
    "description": "Start your day with clarity and intention.",
    "spotify_url": "https://open.spotify.com/playlist/37i9dQZF1DX0UrRvztWcAU",
    "embed_url": "https://open.spotify.com/embed/playlist/37i9dQZF1DX0UrRvztWcAU"
  }
}

Names

POST/api/v1/names

Analyse a name and store the result. Returns meaning, origin, and vibrational profile.

Authentication

App token

Parameters

Name	Type	Required	Description
`name`	string	required	Given name to analyse (JSON request body)

Response example

{
  "data": {
    "name": "Luna",
    "origin": "Latin",
    "meaning": "moon",
    "vibration": "intuitive, reflective, cyclical"
  }
}

GET/api/v1/names

List previously analysed names, paginated.

Authentication

App token

Parameters

Name	Type	Required	Description
`page`	integer	optional	Page number (default: 1)
`limit`	integer	optional	Results per page (default: 20)

Response example

{
  "data": [
    {
      "name": "Luna",
      "origin": "Latin",
      "meaning": "moon"
    },
    {
      "name": "Sol",
      "origin": "Latin",
      "meaning": "sun"
    }
  ],
  "page": 1,
  "total": 12
}

Personality

GET/api/v1/personality

Derive a personality archetype from astrological and numerological inputs. All params are optional — provide as many as available for a richer result.

Authentication

App token

Parameters

Name	Type	Required	Description
`birthdate`	string	optional	YYYY-MM-DD
`time_of_birth`	string	optional	HH:MM (24h)
`location`	string	optional	City and country, e.g. Santiago, Chile
`name`	string	optional	Given name for numerological input

Response example

{
  "data": {
    "archetype": "The Lantern",
    "traits": ["introspective", "guiding", "luminous"],
    "summary": "You illuminate paths for others while navigating your own."
  }
}

Quotes

GET/api/v1/quotes

Today's daily spiritual quote.

Authentication

App token

Response example

{
  "data": {
    "quote": "Soften the grip. Stay.",
    "author": "—"
  }
}

Geocoding

GET/api/v1/geocoding/cities

Search cities by name. Use this to resolve birth locations before calling /natal or /personality.

Authentication

App token

Parameters

Name	Type	Required	Description
`q`	string	required	City name to search, e.g. Santiago

Response example

{
  "data": [
    {
      "name": "Santiago",
      "country": "Chile",
      "lat": -33.4569,
      "lng": -70.6483
    },
    {
      "name": "Santiago de Compostela",
      "country": "Spain",
      "lat": 42.8782,
      "lng": -8.5448
    }
  ]
}