{"openapi":"3.1.0","info":{"title":"Luckboo Reading API","version":"1.0.0","summary":"Generate a playful birth-chart × home luck reading as JSON.","description":"Public, free, no-auth JSON API behind luckboo.com. Send a birth date and a place (listing link, street, or neighborhood); get back a 0–100 luck score, a mood word, three reasons it fits, a watch-out, a move-in ritual and a share line. Luckboo readings are for inspiration, not housing, legal, or financial advice.\n\nFair use: the same caps as the website apply (about 10 generated readings per user per hour and a global daily cap). Over the cap, or if the model is unavailable, you still get HTTP 200 with a sample reading; check the `x-reading-source` response header (`llm` = freshly generated; `fixture`, `fixture-limited`, `fixture-error` = sample).","contact":{"email":"hello@luckboo.com","url":"https://luckboo.com/developers"},"termsOfService":"https://luckboo.com/terms"},"servers":[{"url":"https://luckboo.com"}],"externalDocs":{"url":"https://luckboo.com/developers","description":"Developer & agent guide"},"paths":{"/api/v1/reading":{"post":{"operationId":"createReading","summary":"Generate a luck reading for a person and a home","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadingRequest"},"examples":{"neighborhood":{"value":{"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"}},"listing":{"value":{"birthDate":"1990-02-03","place":{"mode":"url","value":"https://www.redfin.com/NY/Brooklyn/45-Park-Pl"},"propertyType":"buy"}}}}}},"responses":{"200":{"description":"A reading (generated, or a sample when limited; see x-reading-source).","headers":{"x-reading-source":{"description":"llm | fixture | fixture-limited | fixture-error","schema":{"type":"string","enum":["llm","fixture","fixture-limited","fixture-error"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Reading"}}}},"400":{"description":"Missing birthDate or place.value, or invalid JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"describeReadingApi","summary":"Machine-readable pointer to these docs with an example body","responses":{"200":{"description":"API description","content":{"application/json":{}}}}}}},"components":{"schemas":{"ReadingRequest":{"type":"object","required":["birthDate","place"],"properties":{"birthDate":{"type":"string","format":"date","description":"YYYY-MM-DD","example":"1994-07-21"},"birthTime":{"type":["string","null"],"pattern":"^\\d{2}:\\d{2}$","description":"24h HH:MM, or null if unknown"},"birthPlace":{"type":"string","maxLength":120,"description":"City, country (optional)"},"lifeChips":{"type":"array","maxItems":2,"items":{"type":"string","enum":["new city","couple move","solo reset","career shift","soft landing","wild card"]},"description":"Up to two life-context chips"},"place":{"$ref":"#/components/schemas/Place"},"propertyType":{"type":"string","enum":["rent","buy"],"default":"rent"},"moveInDate":{"type":"string","format":"date","description":"Optional planned move-in day (YYYY-MM-DD, from about a year ago to three years ahead). The reading will comment on the day."}}},"Place":{"type":"object","required":["value"],"properties":{"mode":{"type":"string","enum":["url","address","neighborhood"],"default":"neighborhood"},"value":{"type":"string","maxLength":300,"description":"Listing URL, street address, or neighborhood"},"vibeWords":{"type":"array","maxItems":3,"items":{"type":"string","maxLength":40}}}},"Reading":{"type":"object","required":["score","moodWord","whyFit","watchOut","ritual","shareLine","chipLabel","whisperedPlace","disclaimer","propertyType"],"properties":{"score":{"type":"integer","minimum":0,"maximum":100},"moodWord":{"type":"string","enum":["Anchored","Sparks","Soft no"],"description":"Anchored 70–100, Sparks 40–69, Soft no 0–39"},"whyFit":{"type":"array","minItems":3,"maxItems":3,"items":{"type":"string"}},"watchOut":{"type":"string"},"ritual":{"type":"string"},"shareLine":{"type":"string"},"chipLabel":{"type":"string"},"whisperedPlace":{"type":"string","description":"Street or neighborhood only, never house/unit numbers"},"disclaimer":{"type":"string","example":"Luckboo readings are for inspiration, not housing, legal, or financial advice."},"propertyType":{"type":"string","enum":["rent","buy"]},"moveInDate":{"type":"string","format":"date"},"headline":{"type":"string","description":"Short shareable hook (also returned as shareLine)"},"booLine":{"type":"string","description":"One line from Boo, the mascot"},"whyIcons":{"type":"array","items":{"type":"string","enum":["sun","moon","number","place","day","chip","vibe"]}},"fullReading":{"type":"string"},"signals":{"type":"object","description":"Computed in code, never by the model: sun sign (and moon sign when certain), life path, place number (house digits or name), element harmony, lucky color and day."},"luckyTips":{"type":"object","properties":{"room":{"type":"string"},"roomWhy":{"type":"string"},"color":{"type":"object","properties":{"name":{"type":"string"},"hex":{"type":"string"}}},"day":{"type":"string"},"object":{"type":"string"}}},"moveIn":{"type":"object","description":"Present when moveInDate was sent: moon phase, weekday ruler, Mercury retrograde, a verdict, a 7-day strip and an optional better nearby day."},"sample":{"type":"boolean","description":"True when the words are a sample (Boo is resting); chart facts are still real"}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}}}}