Public API

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

Card of the Day

Returns a deterministic card of the day for a given deck. All users see the same card on a given day for a given deck. The card changes daily at midnight UTC.

GET/api/card-of-the-day

Query Parameters

Parameter	Type	Description
`deckId`	string (optional)	The ID of a published deck. If omitted, the default free deck is used.

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 daily interpretation for collective guidance.

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 daily interpretation for collective guidance.

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.

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.