Public API

Free, public endpoints for integrating Mystic Cards into your projects. No authentication required.

Card of the Day

Returns a daily tarot card. Operates in two modes depending on whether a deckId is provided. Without a deckId, returns the pre-generated daily oracle: a free deck rotated each day, with an AI-written collective interpretation included. With a deckId, returns a deterministic card for that specific deck without an interpretation. All users see the same card for a given deck on a given day. The card changes daily at midnight UTC.

GET/api/card-of-the-day

Query Parameters

Parameter	Type	Description
`deckId`	string (optional)	ID of any published deck. When provided, returns a deterministic card for that deck — the interpretation field will not be present. When omitted, returns the pre-generated daily oracle with a rotating free deck and an AI interpretation.

Example Request

curl https://getmystic.cards/api/card-of-the-day

Example Response

{
  "date": "2026-02-16",
  "card": {
    "id": "abc123",
    "name": "The Star",
    "displayName": "The Star",
    "arcana": "major",
    "suit": null,
    "number": 17,
    "imageUrl": "/cards/star.jpg",
    "reversedImageUrl": "/api/card-of-the-day/image",
    "reversed": false,
    "uprightMeaning": "Hope, inspiration, generosity...",
    "reversedMeaning": "Lack of faith, despair...",
    "keywords": "hope,faith,renewal"
  },
  "deck": {
    "id": "deck-1",
    "name": "Rider-Waite-Smith"
  },
  "interpretation": "Today The Star illuminates your path..."
}

Response Fields

Field	Description
`date`	The date for this card selection (YYYY-MM-DD in UTC).
`card`	The selected card with meanings, image URL, and reversal status.
`card.imageUrl`	The upright card image URL. Always points to the original image regardless of reversal status.
`card.reversedImageUrl`	Endpoint that serves the card image rotated 180° when reversed. Use this for a pre-rotated reversed image.
`card.reversed`	Whether the card appears reversed today.
`card.displayName`	The card name, with any deck-specific aliases applied.
`deck`	The deck ID and name used for the selection.
`interpretation`	An AI-generated collective reading for the day. Only present on the oracle path (no deckId passed). Absent when a specific deckId is used.

Rider-Waite Card of the Day

Returns a deterministic daily card drawn exclusively from the Rider-Waite deck. Same response shape as Card of the Day. No query parameters.

GET/api/card-of-the-day/rider-waite

Example Request

curl https://getmystic.cards/api/card-of-the-day/rider-waite

Example Response

{
  "date": "2026-03-18",
  "card": {
    "id": "abc456",
    "name": "The Moon",
    "displayName": "The Moon",
    "arcana": "major",
    "suit": null,
    "number": 18,
    "imageUrl": "/cards/moon.jpg",
    "reversedImageUrl": "/api/card-of-the-day/image",
    "reversed": true,
    "uprightMeaning": "Illusion, fear, the unconscious...",
    "reversedMeaning": "Release of fear, repressed emotion...",
    "keywords": "illusion,fear,subconscious"
  },
  "deck": {
    "id": "rider-waite-1773856090826",
    "name": "Rider-Waite Tarot"
  },
  "interpretation": "Today The Moon invites you to examine..."
}

Hexagram of the Day

Returns a deterministic I Ching hexagram of the day. All users see the same hexagram on a given day. The hexagram changes daily at midnight UTC.

GET/api/hexagram-of-the-day

Example Request

curl https://getmystic.cards/api/hexagram-of-the-day

Example Response

{
  "date": "2026-03-05",
  "hexagram": {
    "number": 11,
    "name": "Peace",
    "chineseName": "Tai",
    "upperTrigram": "Earth",
    "lowerTrigram": "Heaven",
    "judgment": "Peace. The small departs, the great approaches...",
    "image": "Heaven and Earth unite: the image of Peace..."
  },
  "imageUrl": "/hexagrams/11.svg",
  "interpretation": "Today Hexagram 11 invites harmony and balance..."
}

Response Fields

Field	Description
`date`	The date for this card selection (YYYY-MM-DD in UTC).
`hexagram.number`	The hexagram number (1-64).
`hexagram.name`	The English name of the hexagram.
`hexagram.chineseName`	The traditional Chinese name of the hexagram.
`hexagram.upperTrigram`	The upper trigram name (e.g. Heaven, Earth, Water).
`hexagram.lowerTrigram`	The lower trigram name (e.g. Heaven, Earth, Water).
`hexagram.judgment`	King Wen's judgment text for the hexagram.
`hexagram.image`	The Duke of Zhou's image text for the hexagram.
`imageUrl`	Path to the hexagram's SVG line diagram.
`interpretation`	An AI-generated collective reading for the day. Only present on the oracle path (no deckId passed). Absent when a specific deckId is used.

Weekly Horoscope

Returns AI-generated weekly horoscopes for all 12 zodiac signs. Updated every Sunday at 6 AM UTC. If the current week's horoscope is not yet available, the most recent one is returned.

GET/api/astrology/weekly

Example Request

curl https://getmystic.cards/api/astrology/weekly

Example Response

{
  "weekOf": "2026-03-09",
  "signs": [
    {
      "sign": "Aries",
      "element": "Fire",
      "reading": "This week brings a surge of creative energy...",
      "transits": "Mars in Gemini squares Neptune...",
      "keyTheme": "Creative Breakthroughs",
      "compatibility": "Leo"
    },
    ...
  ]
}

Response Fields

Field	Description
`weekOf`	The Monday date (YYYY-MM-DD) representing the start of the horoscope week.
`signs`	Array of 12 horoscope readings, one per zodiac sign.
`signs[].sign`	The zodiac sign name (e.g. Aries, Taurus).
`signs[].element`	The sign's element (Fire, Earth, Air, or Water).
`signs[].reading`	The full weekly horoscope reading for this sign.
`signs[].transits`	Notable planetary transits affecting this sign during the week.
`signs[].keyTheme`	A short phrase summarizing the week's main theme for this sign.
`signs[].compatibility`	The most compatible zodiac sign for the week.

Available Free Decks

These deck IDs can be passed as the deckId parameter to target a specific free deck in your requests.

Deck Name	Deck ID
CBD Tarot	`classic-deck`
The Gilded Vine	`the-gilded-vine-1773866097654`
Rider-Waite	`rider-waite-1773856090826`

Errors

All errors return a JSON object with an error field.

Status	Meaning
`404`	Deck not found or not published. Hexagram not found. No weekly horoscope data available yet.
`500`	Internal server error.

Caching

Responses include a Cache-Control: public, max-age=3600 header. The card of the day is deterministic for a given date and deck, so responses are safe to cache.