Tarot Reading

Draw a tarot card or spread from a 78-card Rider-Waite deck with interpretations. Costs 3 credits.

GET /v1/tarot

Parameters

Name	Type	Required	Description
`spread`	string	No	Spread type: `single` (default), `three`, or `celtic`.

Example request

curl "https://api.gitstrology.dev/v1/tarot?spread=three" \
  -H "X-API-Key: $GITSTROLOGY_API_KEY"

Example response

{
  "data": {
    "spread": "three",
    "cards": [
      {
        "card": {
          "name": "The Star",
          "arcana": "major",
          "number": 17,
          "rank": "XVII",
          "upright": ["hope", "renewal", "inspiration"],
          "reversed": ["despair", "disconnection"],
          "symbol": "★"
        },
        "position": "past",
        "reversed": false,
        "meaning": "hope"
      }
    ],
    "interpretation": "Your past holds hope and renewal..."
  },
  "credits": { "used": 3, "remaining": 97 }
}

Response fields

Field	Type	Description
`data.spread`	string	Spread name (single, three, celtic).
`data.cards`	array	Drawn cards. See below.
`data.interpretation`	string	Combined interpretation of the spread.

Drawn card object

Field	Type	Description
`card`	object	Full card metadata (name, arcana, suit?, number, rank, upright[], reversed[], element?, symbol).
`position`	string	Position in the spread (e.g. "past", "present", "future").
`reversed`	boolean	True if the card is drawn reversed.
`meaning`	string	The active keyword (from upright or reversed).