The Luckboo reading API

Endpoint

POST https://luckboo.com/api/v1/reading with a JSON body. A GET on the same URL returns a short description and an example body. Full schema: /openapi.json.

curl -s https://luckboo.com/api/v1/reading \
  -H 'content-type: application/json' \
  -d '{
    "birthDate": "1994-07-21",
    "birthTime": "08:15",
    "birthPlace": "Austin, USA",
    "lifeChips": ["new city"],
    "place": { "mode": "neighborhood", "value": "Hayes Valley, San Francisco",
               "vibeWords": ["sunlit", "quiet"] },
    "propertyType": "rent",
    "moveInDate": "2026-11-05"
  }'

Request fields

• birthDate (required): YYYY-MM-DD.
• birthTime: HH:MM 24-hour, or null.
• birthPlace: city, country.
• lifeChips: up to 2 of new city, couple move, solo reset, career shift, soft landing, wild card.
• place (required): { mode: "url" | "address" | "neighborhood", value, vibeWords? }.
• propertyType: rent (default) or buy.
• moveInDate: optional YYYY-MM-DD; the reading comments on the day.

Response

{
  "score": 78,
  "moodWord": "Anchored",
  "whyFit": ["…", "…", "…"],
  "watchOut": "…",
  "ritual": "…",
  "shareLine": "…",
  "chipLabel": "…",
  "whisperedPlace": "Hayes Valley",
  "disclaimer": "Luckboo readings are for inspiration, not housing, legal, or financial advice.",
  "propertyType": "rent",
  "moveInDate": "2026-11-05"
}

The x-reading-source header is llm for a freshly generated reading. Over the fair-use cap, or if the model is unavailable, you still get HTTP 200 with a sample reading and a fixture-* source, so your integration never breaks.

Limits & etiquette

• About 10 generated readings per user (IP) per hour, plus a global daily cap shared with the website.
• Keep the small-print line somewhere near the reading: “Luckboo readings are for inspiration, not housing, legal, or financial advice.”
• Don’t send personal data you don’t need. House numbers are stripped from the output anyway.

For browser agents

The form on the home page uses plain labeled inputs: Birth date, Birth time, Birthplace, Life vibe toggles, a Rent or buy radio group, Listing link or Street or neighborhood, Move-in day, and Vibe words, then the Pull my reading button. Start from Check this listing on the landing screen.