cdk-tarot-reading-api

An AWS CDK construct that deploys a complete serverless tarot card reading API with all 78 tarot card meanings. Deploy your own tarot reading API to AWS in minutes with a single construct.

Built by Deckaura — free tarot reading tools, tarot card meanings, and premium tarot decks.

What is a Tarot Card Reading API?

A tarot card reading API provides programmatic access to tarot card meanings, daily tarot cards, yes or no tarot readings, and multi-card spreads. This construct deploys a production-ready API on AWS Lambda and API Gateway that your applications, chatbots, Alexa skills, or websites can call to deliver tarot readings.

The API includes the complete 78-card tarot deck — all 22 Major Arcana cards (The Fool through The World) and 56 Minor Arcana cards (Cups, Pentacles, Swords, and Wands) — with upright meanings, reversed meanings, love interpretations, career guidance, yes/no energy, and keywords for every card.

Installation

npm install cdk-tarot-reading-api

Quick Start

import * as cdk from 'aws-cdk-lib';
import { TarotReadingApi } from 'cdk-tarot-reading-api';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'TarotStack');

// Deploy with defaults
const tarot = new TarotReadingApi(stack, 'TarotApi');

// Or customize
const tarotCustom = new TarotReadingApi(stack, 'TarotApiCustom', {
  memorySize: 256,
  timeout: cdk.Duration.seconds(15),
  stageName: 'v1',
  enableCors: true,
});

// Access the API URL
new cdk.CfnOutput(stack, 'Url', { value: tarot.apiUrl });

API Endpoints

Once deployed, your API provides the following endpoints:

| Endpoint | Method | Description | |----------|--------|-------------| | / | GET | API information with links to all endpoints | | /card/random | GET | Draw a random tarot card with full meaning | | /card/daily | GET | Today's daily tarot card — same card for all users each day | | /reading/yesno | GET | Yes or No tarot reading using 3-card majority vote | | /reading/three | GET | Past, Present, Future three-card tarot spread | | /cards | GET | List all 22 Major Arcana tarot cards |

Example: Random Tarot Card Draw

curl https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/card/random

{
  "card": {
    "name": "The Star",
    "arcana": "major",
    "upright": "Hope, faith, purpose, renewal, spirituality",
    "reversed": "Lack of faith, despair, disconnection",
    "love": "Renewed hope in love, healing",
    "career": "Inspiration returns, dream career aligning",
    "yesNo": "yes",
    "keywords": ["hope", "inspiration", "renewal"],
    "element": "Air"
  },
  "orientation": "upright",
  "meaning": "Hope, faith, purpose, renewal, spirituality",
  "learn_more": "https://deckaura.com/blogs/guide/the-star-tarot-meaning",
  "powered_by": "https://deckaura.com"
}

Example: Daily Tarot Card

Every user who calls /card/daily on the same calendar day receives the same tarot card. The card changes at midnight UTC, making it ideal for daily tarot practice, morning ritual apps, or tarot card of the day features.

Example: Yes or No Tarot Reading

The yes or no tarot endpoint draws three cards and uses a majority vote system. Each tarot card carries inherent yes, no, or maybe energy. Cards like The Sun, The Star, and Ace of Cups carry strong yes energy, while The Tower, Death, and Five of Pentacles lean toward no.

Example: Three-Card Tarot Spread

The three-card spread reveals Past, Present, and Future positions — the most popular tarot spread for quick but insightful readings.

Understanding the 78 Tarot Cards

The API covers the complete tarot deck used in tarot card readings worldwide:

Major Arcana (22 Cards)

The Major Arcana represents life's spiritual lessons and karmic themes. These cards carry powerful energy in any tarot reading:

The Fool, The Magician, The High Priestess, The Empress, The Emperor, The Hierophant, The Lovers, The Chariot, Strength, The Hermit, Wheel of Fortune, Justice, The Hanged Man, Death, Temperance, The Devil, The Tower, The Star, The Moon, The Sun, Judgement, The World.

Minor Arcana (56 Cards)

The Minor Arcana reflects day-to-day influences through four suits:

• Cups (Water) — Emotions, love, relationships, intuition
• Pentacles (Earth) — Money, career, material security, health
• Swords (Air) — Thoughts, conflict, truth, intellectual challenges
• Wands (Fire) — Passion, energy, ambition, creativity

Each suit contains Ace through Ten plus Page, Knight, Queen, and King.

Tarot Reading Types Explained

Yes or No Tarot Reading

The fastest way to get tarot guidance on binary questions. The API draws three cards and determines the answer based on each card's inherent yes/no energy. Learn more about yes or no tarot readings.

Daily Tarot Card

A single card drawn for each calendar day that represents the collective energy and theme. Ideal for building a daily tarot card practice. Try the daily tarot card tool.

Three-Card Tarot Spread

The classic Past, Present, Future layout that reveals where you have been, where you are, and where you are heading. Learn three-card tarot spread techniques.

Celtic Cross Tarot Spread

The most comprehensive 10-card spread in tarot history. Read the Celtic Cross guide.

Love Tarot Reading

A 5-card spread exploring You, Partner, Challenge, Advice, and Outcome. Try the love tarot reading tool.

Construct Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | memorySize | number | 128 | Lambda memory in MB | | timeout | Duration | 10s | Lambda timeout | | stageName | string | prod | API Gateway stage | | enableCors | boolean | true | Enable CORS headers |

Outputs

| Property | Type | Description | |----------|------|-------------| | api | RestApi | API Gateway REST API instance | | handler | Function | Lambda function instance | | apiUrl | string | The deployed API endpoint URL |

Free Tarot Tools by Deckaura

Practice tarot reading online with these free interactive tools:

• Free Tarot Reading — Interactive reading with 5 spread types
• Daily Tarot Card — Your tarot card of the day
• Tarot Birth Card Calculator — Find your birth card
• Numerology Calculator — Calculate your life path number
• Spirit Animal Quiz — Discover your spirit animal
• Angel Number Calculator — Angel number meanings
• Moon Phase Today — Current moon phase and meaning
• Birth Chart Calculator — Free natal chart reading
• Zodiac Compatibility — Check zodiac sign compatibility
• Biorhythm Calculator — Physical, emotional, intellectual cycles
• All 78 Tarot Card Meanings — Complete guide

Related Packages

• tarot-card-meanings — NPM package with all 78 card meanings (no AWS dependency)
• tarot-card-meanings on PyPI — Python package for tarot card data
• Tarot Reading on GitHub Pages — Free web-based tarot reading app
• Tarot API on AWS SAR — One-click deploy via Serverless Application Repository

Use Cases

• Tarot reading websites — Add tarot readings to any website with API calls
• Alexa skills — Build a voice-activated tarot reading skill
• Discord/Telegram bots — Create a tarot bot for your community
• Mobile apps — Power a tarot app without managing infrastructure
• Daily horoscope features — Use the daily card endpoint for content
• AI-powered tarot — Combine with LLMs for personalized interpretations

Blog Post

Read How I Shipped a Tarot Card API to Every Major Package Registry in One Day for the full story behind this project.

License

MIT License — Free to use in any project.

Built with love by Deckaura — Shop tarot decks and oracle cards with free worldwide shipping.