Skip to main content

Tarot Cards by Suit

Returns all 14 cards in a given suit: wands, cups, swords, or pentacles. Wands=fire/career, Cups=water/emotions, Swords=air/intellect, Pentacles=earth/material.

Endpoint

GET /v1/tarot/suits/{suit}

Request parameters

FieldTypeRequiredDescription
suitstringYes

Example request

curl -X GET "https://api.asterwise.com/v1/tarot/suits/cups" \
-H "Authorization: Bearer YOUR_API_KEY"

Example response

{
"success": true,
"message": "success",
"data": [
{
"id": "ace-of-cups",
"name": "Ace of Cups",
"arcana_type": "minor",
"suit": "cups",
"number": 1,
"element": "water",
"astrology_correspondence": "Water signs (Cancer, Scorpio, Pisces)",
"keywords_upright": [
"love",
"new relationships",
"... and 4 more items"
],
"keywords_reversed": [
"emotional loss",
"blocked creativity",
"... and 2 more items"
],
"upright_meaning": "The Ace of Cups brings an outpouring of love, emotional fulfilment, and spiritual connection. A new relationship or crea…",
"reversed_meaning": "Reversed, the Ace of Cups signals emotional blockage, repressed feelings, or a new relationship that does not reach its…",
"yes_no": "yes",
"description": "A hand offers a cup from the clouds. Five streams of water overflow from it. A dove descends, placing a communion wafer…"
},
{
"id": "two-of-cups",
"name": "Two of Cups",
"arcana_type": "minor",
"suit": "cups",
"number": 2,
"element": "water",
"astrology_correspondence": "Venus in Cancer",
"keywords_upright": [
"unified love",
"partnership",
"... and 3 more items"
],
"keywords_reversed": [
"disharmony",
"imbalance",
"... and 2 more items"
],
"upright_meaning": "The Two of Cups represents a profound emotional and romantic connection between two people. Mutual attraction, trust, an…",
"reversed_meaning": "Reversed, the Two of Cups signals imbalance, disharmony, or communication breakdown disrupting a partnership. Address th…",
"yes_no": "yes",
"description": "Two figures face each other, each holding a cup. A caduceus rises between them, topped with a winged lion head. Their ex…"
},
"... and 12 more items"
]
}

Response fields

FieldTypeDescription
successbooleanTrue if the request succeeded
messagestringHuman-readable status message
dataarray[object]The endpoint response payload
data[].idstringUnique slug identifier e.g. 'the-fool'
data[].namestringFull card name e.g. 'The Fool'
data[].arcana_typestring'major' or 'minor'
data[].suitstring | nullSuit for minor arcana: wands, cups, swords, pentacles. Null for major arcana.
data[].numberintegerCard number. Major arcana: 0-21. Minor arcana: 1=Ace, 11=Page, 12=Knight, 13=Queen, 14=King.
data[].elementstringElemental correspondence: fire, water, air, earth, spirit
data[].astrology_correspondencestringAstrological planet or sign correspondence
data[].keywords_uprightarray[string]Upright keywords
data[].keywords_reversedarray[string]Reversed keywords
data[].upright_meaningstringFull upright interpretation
data[].reversed_meaningstringFull reversed interpretation
data[].yes_nostringYes/No polarity: 'yes', 'no', or 'maybe'
data[].descriptionstringVisual description of the card imagery

Errors

CodeDescriptionReference
authentication_failedMissing or invalid API key.authentication_failed
ephemeris_unavailableUpstream ephemeris service error.ephemeris_unavailable
insufficient_tierAPI key tier does not include this endpoint.insufficient_tier
internal_errorUnexpected server error.internal_error
ip_rate_limit_exceededToo many requests in a short window.ip_rate_limit_exceeded
payload_too_largeRequest body exceeds the size limit.payload_too_large
resource_not_foundReferenced resource was not found.resource_not_found
validation_errorRequest body failed schema validation.validation_error