• Servicing Endpoints
  • Tarot Post Endpoint Summary
  • Tarot Reading Session Workflow Brief
  • Triggers on User Request
• Examples
  • 1. Generate Natal Chart: POST /astrology/user_astrology/
  • Tarot Reading Example
    • 2. Tarot Reading Prediction: POST /tarot/tarot_prediction/
    • 3. Tarot Insight Stats: POST /insight_stats/

Tarot’s Rest API is built on FastAPI and uvicorn and served with Google Cloud Run. This stack was chosen based on its ease for deployment.

The features this endpoint entails:

• Complete Tarot Session Readings
• User Astrology Insights
• User Tarot Session Insights
• Stripe Services

Servicing Endpoints

Tarot Post Endpoint Summary

---
config:
  theme: redux-color
---
sequenceDiagram
    autonumber
    actor Client
    participant TarotAPI as /tarot
    participant Taro as TaroEngine

    Client->>TarotAPI: POST /tarot/predict/
    TarotAPI->>Taro: predict
    Taro-->>TarotAPI: session result
    TarotAPI-->>Client: 200 OK

    Client->>TarotAPI: POST /tarot/drawCards/
    TarotAPI->>Taro: draw cards
    Taro-->>TarotAPI: cards
    TarotAPI-->>Client: 200 OK

    Client->>TarotAPI: POST /tarot/predict-combination/
    TarotAPI->>Taro: combined prediction
    Taro-->>TarotAPI: session result
    TarotAPI-->>Client: 200 OK

Tarot Reading Session Workflow Brief

Called on events to complete any type of tarot readings.

---
config:
  theme: redux-color
---
flowchart TD
    subgraph TarotAPI["/tarot router"]
        P["POST /tarot/predict/"]
        D["POST /tarot/drawCards/"]
        PC["POST /tarot/predict-combination/"]
    end

    TaroEngine["TaroEngine service"]

    P -->|"TarotSessionInput, TarotSessionOutput"| TaroEngine
    D -->|"TarotDrawInput, cards JSON"| TaroEngine
    PC -->|"TarotSessionInput, TarotSessionOutput"| TaroEngine

Triggers on User Request

This endpoint is triggered for events like refreshing personal insights on their dashboard in app.

---
config:
  theme: redux-color
---
flowchart TD
    subgraph UserAPI["/user router"]
        RI["POST /user/refresh-insights/"]
        AI["POST /user/astro_info/"]
    end

    Auth["FirebaseUserAuth"]
    DB["CRUD layer (profiles, insights)"]
    Astro["get_astro_data()"]

    RI --> Auth
    RI --> DB

    AI --> Auth
    AI --> DB
    AI --> Astro

Examples

Swagger Docs

Once setup and locally running, access interactive API documentation at defaul local sites:

• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc

1. Generate Natal Chart: POST /astrology/user_astrology/

Generate astrological insights for a given user based on birth details.

Example Input:

{
  "birth_date": "1994-02-20",
  "birth_time": "03:15",
  "birth_place": "Australia/Sydney"
}

Example Output:

{
  "birth_date": "1994-02-20",
  "birth_time": "03:15",
  "birth_place": "Australia/Sydney",
  "sun_sign": "Pisces",
  "moon_sign": "Leo",
  "rising_sign": "Sagittarius",
  "house_placements": {
    "1st House": "Sagittarius",
    "2nd House": "Capricorn"
  },
  "planet_positions": {},
  "aspects": [],
  "elements": {
    "Water": 3,
    "Fire": 2
  },
  "modalities": {},
  "dominant_element": "Water",
  "dominant_modality": "Mutable"
}

Tarot Reading Example

2. Tarot Reading Prediction: POST /tarot/tarot_prediction/

Returns a narrative/storytelling interpretation of the reading. Example Input:

{
  "user": {
    "id": "12345",
    "username": "julie.lenova",
    "first_name": "Julie",
    "last_name": "Lenova",
    "birth_date": "21-03-1999"
  },
  "tarot": {
    "timestamp": "2025-06-22T02:30:00",
    "question": "When will I see Pookie?",
    "reading_mode": "three_card",
    "drawn_cards": [
      "two of cups",
      "wheel of fortune",
      "Death"
    ]
  }
}

Example Output:

{
  "detail": [
    {
      "msg": "Pookie is dead. Move on.",
      "type": "string"
    }
  ]
}

3. Tarot Insight Stats: POST /insight_stats/

Returns statistical summaries of a Tarot spread reading. Schema: • num_cards (int) • king_count, queen_count, knight_count, page_count (court counts) • wand_count, coin_count, sword_count, cup_count (suit counts) • total_courts (int) Example Input:

{
  "reading_mode": "three_card",
  "drawn_cards": [
    "ace of wands",
    " nine of cups ",
    "two of swords"
  ]
}

Example Output:

{
  "num_cards": 0,
  "king_count": 0,
  "queen_count": 0,
  "knight_count": 0,
  "page_count": 0,
  "total_courts": 0,
  "wand_count": 0,
  "coin_count": 0,
  "sword_count": 0,
  "cup_count": 0
}