{ "openapi": "3.1.0", "info": { "title": "astrom8-api", "version": "0.1.0", "description": "Western ephemeris, daily horoscopes (cache), BaZi compatibility with WizeOS consumer contract subsets." }, "paths": { "/openapi.json": { "get": { "summary": "This OpenAPI document", "responses": { "200": { "description": "OpenAPI JSON" } } } }, "/docs": { "get": { "summary": "Interactive API documentation (Scalar)", "responses": { "200": { "description": "HTML page with Scalar API Reference (loads `/openapi.json` or `DOCS_OPENAPI_URL`)" } } } }, "/v1/planets": { "get": { "summary": "Planet positions", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "dt", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Planet snapshot" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/natal-chart": { "post": { "summary": "Natal chart", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NatalChartRequest" } } } }, "responses": { "200": { "description": "Chart (+ optional interpretation)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/horoscope/{sign}": { "get": { "summary": "Daily horoscope (legacy v1)", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Daily text" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/bazi": { "post": { "summary": "BaZi (v1 envelope)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaziRequest" } } } }, "responses": { "200": { "description": "Pillar chart (+ optional interpretation)" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/horoscope/sign/daily/text": { "post": { "summary": "Daily horoscope text (Wave D — optional mood, lucky_number, lucky_color when pre-generated row includes them)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyHoroscopeRequest" } } } }, "responses": { "200": { "description": "Daily horoscope payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyHoroscopeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v3/chinese/bazi": { "post": { "summary": "BaZi pillar chart from BirthSubjectInput (same shape as `/v1/bazi` subject branch)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthSubjectInput" } } } }, "responses": { "200": { "description": "Chinese BaZi contract JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BaziResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/korean/saju": { "post": { "summary": "Korean Saju MVP report from BirthSubjectInput: four pillars, five-element balance, day master strength, ten gods, and a short localized reading", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SajuRequest" } } } }, "responses": { "200": { "description": "Korean Saju report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SajuResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/numerology/core-numbers": { "post": { "summary": "Wave A — Pythagorean core numbers (same arithmetic as `/api/v3/numerology/core-numbers`)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumerologyCoreRequest" } } } }, "responses": { "200": { "description": "Core numbers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumerologyCoreResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/vedic/panchang": { "post": { "summary": "Wave C — Panchang: response includes English + Thai labels (`name_th`, `lord_th`, `moon_phase_th`, karana) where applicable; Lahiri sidereal nakṣatra & yoga; tithī/karaṇa/phase from lunar elongation; same memo/cache semantics as before.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PanchangRequest" } } } }, "responses": { "200": { "description": "Panchang", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PanchangResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/tarot/cards/daily": { "post": { "summary": "Wave E — Daily tarot card (deterministic per date + locale key; response includes `orientation` upright|reversed; static meanings — no `image_url`)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarotDailyRequest" } } } }, "responses": { "200": { "description": "Daily card payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarotDailyResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/tarot/reports/three-card": { "post": { "summary": "Wave E — Three-card spread (distinct random draws; Claude JSON; 503 if no API key, 502 if model output unusable — no credit charge on failure; generic 500 body on other errors)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarotSpreadRequest" } } } }, "responses": { "200": { "description": "Cards + reading_summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarotSpreadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGatewayInterpretation" }, "503": { "$ref": "#/components/responses/ServiceUnavailableInterpretation" } } } }, "/api/v3/tarot/reports/celtic-cross": { "post": { "summary": "Wave E — Celtic cross (10 draws; Claude JSON; 503 if no API key, 502 if model output unusable — no credit charge on failure; generic 500 body on other errors)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarotSpreadRequest" } } } }, "responses": { "200": { "description": "Cards + reading_summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarotSpreadResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" }, "502": { "$ref": "#/components/responses/BadGatewayInterpretation" }, "503": { "$ref": "#/components/responses/ServiceUnavailableInterpretation" } } } }, "/api/v3/vedic/vimshottari-dasha": { "post": { "summary": "Wave C — Vimshottari Dasha (9 mahādasha × 9 antardaśā, 120y cycle): Lahiri sidereal Moon nakṣatra; `startDate`/`endDate` are civil-calendar dates in the birthplace offset (`timezoneOffsetMinutes`).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthSubjectInput" } } } }, "responses": { "200": { "description": "Dasha tree", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VimshottariResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/vedic/manglik-dosha": { "post": { "summary": "Wave B — Manglik/Kuja (Lahiri sidereal Mars, whole-sign houses 1/4/7/8/12)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthSubjectInput" } } } }, "responses": { "200": { "description": "Manglik assessment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManglikResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/vedic/sade-sati": { "post": { "summary": "Wave B — Shani Sade Sati belts vs natal sidereal Moon; dates ≈ Saturn’s stay in transit sign", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthSubjectInput" } } } }, "responses": { "200": { "description": "Sade Sati phases", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SadeSatiResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/numerology/core-numbers": { "post": { "summary": "Pythagorean core numbers (`full_name`, `birth_date`)", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumerologyCoreRequest" } } } }, "responses": { "200": { "description": "Core numbers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumerologyCoreResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/vedic/kundli-matching": { "post": { "summary": "Wave F — Ashta Koota / Guna Milan (36 pts): Lahiri sidereal Moon; whole-sign Bhakoot/Varna; Manglik from Kuja houses; Thai recommendation string", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KundliMatchingRequest" } } } }, "responses": { "200": { "description": "Matching score + breakdown", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KundliMatchingResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/reports/compatibility": { "post": { "summary": "Phase 9.6 — unified compatibility report: Western synastry aspects + BaZi Day Master five-element relationship + Thai zodiac trine/liu-he/clash. Programmatic Thai/English summaries; weighted overall score (0-100).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityRequest" } } } }, "responses": { "200": { "description": "Combined compatibility result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompatibilityResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/thai/calendar/day": { "post": { "summary": "Thai auspicious calendar (single date)", "description": "Returns Thai Buddhist holy day (วันพระ), zodiac year clash (ปีชง), and three reuk systems (ทักษา + ฤกษ์บน + ดิถี) for the given date.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "timezoneOffsetMinutes", "latitude", "longitude" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-05-08" }, "timezoneOffsetMinutes": { "type": "integer", "example": 420 }, "latitude": { "type": "number", "example": 13.756 }, "longitude": { "type": "number", "example": 100.502 }, "birth_year": { "type": "integer", "description": "Optional civil birth year for personal ปีชง check." }, "birth_day_of_week": { "type": "string", "enum": [ "sun", "mon", "tue", "wed", "thu", "fri", "sat", "rahu" ], "description": "Optional birthday weekday for personal ทักษา / มหาทักษา. Use 'rahu' for พุธกลางคืน (Wed-night births)." } } } } } }, "responses": { "200": { "description": "Thai calendar day breakdown", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/thai/moon-phase": { "get": { "summary": "Thai moon phase (paksha + illumination + วันพระ)", "description": "Returns the Thai paksha label, lunar day within paksha, phase classification (8 keys), illumination %, and วันพระ flag for the given date. Free tier accessible.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-05-08" } }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "integer", "default": 420, "minimum": -720, "maximum": 840 } }, { "name": "lat", "in": "query", "required": false, "schema": { "type": "number", "default": 13.7563 } }, { "name": "lng", "in": "query", "required": false, "schema": { "type": "number", "default": 100.5018 } } ], "responses": { "200": { "description": "Moon phase + Thai paksha label", "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "buddhist_date", "paksha", "paksha_th", "paksha_en", "lunar_day", "tithi", "thai_label", "phase_key", "phase_th", "phase_en", "illumination_percent", "is_wan_phra", "wan_phra_label_th" ], "properties": { "date": { "type": "string", "format": "date" }, "buddhist_date": { "type": "string" }, "paksha": { "type": "string", "enum": [ "shukla", "krishna" ] }, "paksha_th": { "type": "string", "enum": [ "ข้างขึ้น", "ข้างแรม" ] }, "paksha_en": { "type": "string", "enum": [ "waxing", "waning" ] }, "lunar_day": { "type": "integer", "minimum": 1, "maximum": 15 }, "tithi": { "type": "integer", "minimum": 1, "maximum": 30 }, "thai_label": { "type": "string", "example": "ขึ้น 15 ค่ำ" }, "phase_key": { "type": "string", "enum": [ "new", "waxing_crescent", "first_quarter", "waxing_gibbous", "full", "waning_gibbous", "last_quarter", "waning_crescent" ] }, "phase_th": { "type": "string" }, "phase_en": { "type": "string" }, "illumination_percent": { "type": "number", "minimum": 0, "maximum": 100 }, "is_wan_phra": { "type": "boolean" }, "wan_phra_label_th": { "type": "string", "nullable": true } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/thai/festivals": { "get": { "summary": "Thai festivals + Buddhist holidays for a year", "description": "Returns Thai government, royal, cultural and computed Buddhist holidays (Magha Puja, Visakha Puja, Asalha Puja, Khao Phansa, Ok Phansa, Atthami Puja) for the given year. Accepts CE (>=1900) or BE (>=2400) year. Free tier accessible.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1900, "maximum": 3000, "example": 2026 }, "description": "CE year (>=1900) or BE year (>=2400). BE values are converted internally." } ], "responses": { "200": { "description": "Sorted list of Thai festivals for the year", "content": { "application/json": { "schema": { "type": "object", "required": [ "year_ce", "year_be", "festivals" ], "properties": { "year_ce": { "type": "integer" }, "year_be": { "type": "integer" }, "festivals": { "type": "array", "items": { "type": "object", "required": [ "date", "buddhist_date", "name_th", "name_en", "category", "is_public_holiday" ], "properties": { "date": { "type": "string", "format": "date" }, "buddhist_date": { "type": "string" }, "name_th": { "type": "string" }, "name_en": { "type": "string" }, "category": { "type": "string", "enum": [ "government", "buddhist", "royal", "cultural" ] }, "is_public_holiday": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/reports/thai-calendar/pdf": { "post": { "summary": "Generate Thai calendar PDF report", "description": "Returns a 24h signed URL to a PDF rendering of the Thai-calendar day report (5 reuk systems + Wan Phra + Pee Chong + Panchang brief). Business tier (pro+) only. Costs 10 credits per request because Chromium is launched server-side per call.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "timezoneOffsetMinutes", "latitude", "longitude" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-05-08" }, "timezoneOffsetMinutes": { "type": "integer", "minimum": -720, "maximum": 840, "example": 420 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "example": 13.7563 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "example": 100.5018 }, "birth_year": { "type": "integer", "minimum": 1900, "maximum": 2200, "description": "Optional Gregorian birth year for personal Pee Chong check." }, "birth_day_of_week": { "type": "string", "enum": [ "sun", "mon", "tue", "wed", "thu", "fri", "sat", "rahu" ], "description": "Optional. 'rahu' = born late Wednesday (มหาทักษา system)." }, "locale": { "type": "string", "enum": [ "th", "en" ], "default": "th" } } } } } }, "responses": { "200": { "description": "PDF generated and uploaded; signed URL valid for 24 hours.", "content": { "application/json": { "schema": { "type": "object", "required": [ "pdf_url", "expires_at" ], "properties": { "pdf_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Tier locked — endpoint requires business tier (pro+).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "503": { "description": "PDF generation pipeline temporarily unavailable (e.g. Chromium launch failure or R2 misconfigured).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v3/thai/wheel/image": { "post": { "summary": "Generate Thai มหาทักษา wheel image (PNG)", "description": "Returns a 24h signed URL of a 1024×1024 PNG showing the user's personalized 8-position wheel composited over a Thai aesthetic background. Pro tier only.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "timezoneOffsetMinutes", "birth_day_of_week" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-05-08" }, "timezoneOffsetMinutes": { "type": "integer", "example": 420 }, "birth_day_of_week": { "type": "string", "enum": [ "sun", "mon", "tue", "wed", "thu", "fri", "sat", "rahu" ] }, "birth_year": { "type": "integer", "description": "Optional civil birth year for center animal label." }, "style": { "type": "string", "enum": [ "gold-temple", "modern-pastel", "mystical-dark" ], "default": "gold-temple" } } } } } }, "responses": { "200": { "description": "Wheel image generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/reports/natal/image": { "post": { "summary": "Generate Western natal chart image (PNG)", "description": "Returns a 24h signed URL of a 1024×1024 PNG showing the user's natal chart wheel — zodiac ring, 12 house cusps, 10 planet glyphs, and major aspect lines. Pro tier only. 5 credits per request.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "time", "latitude", "longitude", "timezoneOffsetMinutes" ], "properties": { "date": { "type": "string", "format": "date", "example": "1990-05-20" }, "time": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "example": "08:30:00" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "timezoneOffsetMinutes": { "type": "integer", "minimum": -840, "maximum": 840 }, "ayanamsa": { "type": "string" }, "name": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Optional display name shown in the caption." }, "house_system": { "type": "string", "enum": [ "P", "W", "K", "E" ], "default": "P", "description": "Placidus / Whole-sign / Koch / Equal." }, "style": { "type": "string", "enum": [ "minimal", "ornate", "thai" ], "default": "minimal" }, "locale": { "type": "string", "enum": [ "th", "en" ], "default": "th" } } } } } }, "responses": { "200": { "description": "Natal chart image generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/api/v3/thai/muhurta": { "post": { "summary": "Thai muhurta — best time-of-day windows", "description": "Given a date + event type, returns ranked time-of-day windows by combining tithi quality + nakshatra quality + planetary hora + lagna sign + Rahu Kalam exclusion. Pro tier only. 3 credits per request.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "date", "timezoneOffsetMinutes", "latitude", "longitude", "event_type" ], "properties": { "date": { "type": "string", "format": "date", "example": "2026-05-08" }, "timezoneOffsetMinutes": { "type": "integer", "example": 420 }, "latitude": { "type": "number", "example": 13.756 }, "longitude": { "type": "number", "example": 100.502 }, "event_type": { "type": "string", "enum": [ "wedding", "business_open", "home_move", "ceremony", "general" ] }, "duration_minutes": { "type": "integer", "minimum": 30, "maximum": 480, "default": 60, "description": "Length of the auspicious window the user needs." }, "top_n": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5, "description": "How many best windows to return." }, "locale": { "type": "string", "enum": [ "th", "en" ], "default": "th" } } } } } }, "responses": { "200": { "description": "Ranked best time-of-day windows for the event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MuhurtaResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Forbidden — endpoint requires a higher tier", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/api/v3/reports/hr-screening": { "post": { "summary": "HR talent assessment report", "description": "B2B HR screening: combines BaZi personality profile (Day Master + element distribution), Thaksa career outlook for the next 1–3 years, optional company-candidate elemental compatibility, position-vs-role match, and an LLM-written HR narrative (Thai + English). Optional 24h signed PDF download. Pro tier only. 30 credits per request (heavy — BaZi + Thaksa + LLM × 2 + optional Chromium PDF).", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "candidate", "position" ], "properties": { "candidate": { "type": "object", "required": [ "birth_date", "timezoneOffsetMinutes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "birth_date": { "type": "string", "format": "date", "example": "1992-04-15" }, "birth_time": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "description": "HH:MM. Default '12:00' if missing." }, "birth_day_of_week": { "type": "string", "enum": [ "sun", "mon", "tue", "wed", "thu", "fri", "sat", "rahu" ], "description": "Optional. If missing, derived from birth_date civil weekday." }, "timezoneOffsetMinutes": { "type": "integer", "minimum": -840, "maximum": 840, "example": 420 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90, "default": 13.7563 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180, "default": 100.5018 } } }, "position": { "type": "string", "minLength": 1, "maxLength": 200, "example": "Senior Sales Manager" }, "company": { "type": "object", "required": [ "founding_date" ], "properties": { "founding_date": { "type": "string", "format": "date" }, "industry": { "type": "string", "maxLength": 120 } } }, "outlook_years": { "type": "integer", "minimum": 1, "maximum": 3, "default": 1 }, "include_pdf": { "type": "boolean", "default": false }, "locale": { "type": "string", "enum": [ "th", "en" ], "default": "th" } } } } } }, "responses": { "200": { "description": "Structured HR talent assessment, with both Thai + English narratives and an optional 24h signed pdf_url when include_pdf=true.", "content": { "application/json": { "schema": { "type": "object", "required": [ "request_id", "generated_at", "position", "candidate_summary", "bazi_profile", "thaksa_outlook", "company_fit", "position_match", "hr_narrative_th", "hr_narrative_en", "recommendation", "recommendation_score", "recommendation_factors_th", "recommendation_factors_en" ], "properties": { "request_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "position": { "type": "string" }, "candidate_summary": { "type": "object" }, "bazi_profile": { "type": "object" }, "thaksa_outlook": { "type": "object" }, "company_fit": { "type": [ "object", "null" ] }, "position_match": { "type": "object" }, "hr_narrative_th": { "type": "string" }, "hr_narrative_en": { "type": "string" }, "recommendation": { "type": "string", "enum": [ "strong_hire", "consider", "caution", "not_recommended" ] }, "recommendation_score": { "type": "integer", "minimum": 0, "maximum": 100 }, "recommendation_factors_th": { "type": "string" }, "recommendation_factors_en": { "type": "string" }, "pdf_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Tier locked — endpoint requires pro tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "503": { "description": "Report pipeline temporarily unavailable (LLM provider, R2, or Chromium when include_pdf=true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } } }, "/api/v3/uranian/chart": { "post": { "summary": "Uranian chart", "description": "Hamburg/Uranian 90-degree dial chart with 22 unique factors, 153 planetary midpoints, and clustered planetary pictures. Pro tier only. 8 credits.", "tags": [ "Uranian" ], "security": [ { "ApiKeyAuth": [] } ], "x-credits": 8, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UranianBaseRequest" } } } }, "responses": { "200": { "description": "Uranian chart with positions, midpoints, and planetary pictures.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UranianChartResponse" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Tier locked — endpoint requires pro tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/uranian/midpoints": { "post": { "summary": "Uranian midpoint tree", "description": "Returns planetary midpoints aligned to an anchor factor on the selected Uranian dial. Pro tier only. 5 credits.", "tags": [ "Uranian" ], "security": [ { "ApiKeyAuth": [] } ], "x-credits": 5, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UranianBaseRequest" }, { "type": "object", "required": [ "anchor_point" ], "properties": { "anchor_point": { "type": "string", "enum": [ "Sun", "Moon", "Mercury", "Venus", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", "Pluto", "Cupido", "Hades", "Zeus", "Kronos", "Apollon", "Admetos", "Vulkanus", "Poseidon", "ASC", "MC", "Node", "Earth" ] } } } ] } } } }, "responses": { "200": { "description": "Midpoints aligned to the requested anchor factor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UranianMidpointsResponse" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Tier locked — endpoint requires pro tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/v3/uranian/pictures": { "post": { "summary": "Uranian planetary pictures by life area", "description": "Filters clustered Uranian planetary pictures by life area. Pro tier only. 5 credits.", "tags": [ "Uranian" ], "security": [ { "ApiKeyAuth": [] } ], "x-credits": 5, "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UranianBaseRequest" }, { "type": "object", "required": [ "life_area" ], "properties": { "life_area": { "type": "string", "enum": [ "career", "love", "money", "health", "family", "spiritual" ] } } } ] } } } }, "responses": { "200": { "description": "Life-area filtered Uranian planetary pictures.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UranianPicturesResponse" } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "description": "Tier locked — endpoint requires pro tier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/cultural-intelligence/orgs": { "post": { "summary": "Create Cultural Intelligence organization", "description": "Creates an org-scoped B2B workspace for Cultural Intelligence profiles and readings. Pro tier only.", "tags": ["Cultural Intelligence"], "security": [{ "ApiKeyAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalOrgCreateRequest" } } } }, "responses": { "200": { "description": "Organization created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalOrg" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } }, "/v1/cultural-intelligence/orgs/{org_id}/usage": { "get": { "summary": "Cultural Intelligence usage summary", "tags": ["Cultural Intelligence"], "security": [{ "ApiKeyAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/CulturalOrgId" }], "responses": { "200": { "description": "Metadata-only usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalUsageSummary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/cultural-intelligence/orgs/{org_id}/profiles": { "post": { "summary": "Create encrypted Cultural Intelligence profile", "description": "Stores encrypted birth inputs and returns only non-sensitive profile metadata.", "tags": ["Cultural Intelligence"], "security": [{ "ApiKeyAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/CulturalOrgId" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalProfileCreateRequest" } } } }, "responses": { "200": { "description": "Profile created without raw or encrypted birth data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalProfile" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Duplicate external_id in org.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } } } }, "get": { "summary": "List Cultural Intelligence profiles", "tags": ["Cultural Intelligence"], "security": [{ "ApiKeyAuth": [] }], "parameters": [{ "$ref": "#/components/parameters/CulturalOrgId" }], "responses": { "200": { "description": "Profile list without raw or encrypted birth data.", "content": { "application/json": { "schema": { "type": "object", "required": ["profiles"], "properties": { "profiles": { "type": "array", "items": { "$ref": "#/components/schemas/CulturalProfile" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/cultural-intelligence/orgs/{org_id}/profiles/{profile_id}/daily-energy": { "post": { "summary": "Daily Energy reading envelope", "description": "Returns a short product-ready reflective card for engagement surfaces.", "tags": ["Cultural Intelligence"], "security": [{ "ApiKeyAuth": [] }], "x-credits": 1, "parameters": [ { "$ref": "#/components/parameters/CulturalOrgId" }, { "$ref": "#/components/parameters/CulturalProfileId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tone": { "type": "string", "enum": ["workplace", "playful", "premium", "calm"], "default": "workplace" } } } } } }, "responses": { "200": { "description": "Daily reflection card.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalReadingEnvelope" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/cultural-intelligence/orgs/{org_id}/teams/{team_id}/chemistry-reflection": { "post": { "summary": "Team chemistry reflection", "description": "Returns team conversation themes and guardrails, not employee ranking.", "tags": ["Cultural Intelligence"], "security": [{ "ApiKeyAuth": [] }], "x-credits": 5, "parameters": [ { "$ref": "#/components/parameters/CulturalOrgId" }, { "$ref": "#/components/parameters/CulturalTeamId" } ], "responses": { "200": { "description": "Team conversation payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalTeamReflection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/cultural-intelligence/orgs/{org_id}/campaigns/content-pack": { "post": { "summary": "Campaign content pack", "description": "Returns culturally resonant copy variants for loyalty, wellness, finance, ecommerce, or community campaigns.", "tags": ["Cultural Intelligence"], "security": [{ "ApiKeyAuth": [] }], "x-credits": 5, "parameters": [{ "$ref": "#/components/parameters/CulturalOrgId" }], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalCampaignRequest" } } } }, "responses": { "200": { "description": "Campaign copy variants.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CulturalCampaignResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Use the raw API key as the Bearer token, or send X-API-Key instead." } }, "parameters": { "CulturalOrgId": { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }, "CulturalProfileId": { "name": "profile_id", "in": "path", "required": true, "schema": { "type": "string" } }, "CulturalTeamId": { "name": "team_id", "in": "path", "required": true, "schema": { "type": "string" } } }, "schemas": { "JsonError": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Stable slug (e.g. unauthorized, payment_required, internal_server_error)." }, "message": { "type": "string", "description": "Human-readable message safe for clients." }, "code": { "type": "string", "description": "Optional provider-specific code." }, "request_id": { "type": "string", "description": "Correlation id when middleware sets it." } } }, "BirthSubjectInput": { "type": "object", "required": [ "date", "time", "latitude", "longitude", "timezoneOffsetMinutes" ], "properties": { "ayanamsa": { "type": "string", "enum": [ "lahiri" ], "default": "lahiri" }, "date": { "type": "string", "format": "date", "examples": [ "1992-04-15" ] }, "time": { "type": "string", "pattern": "^\\d{2}:\\d{2}(:\\d{2})?$", "examples": [ "08:30:00" ] }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "timezoneOffsetMinutes": { "type": "integer", "minimum": -840, "maximum": 840 } } }, "WhiteLabelBrandFields": { "type": "object", "description": "Optional white-label AI voice controls for endpoints that generate LLM interpretation text.", "properties": { "brand_name": { "type": "string", "minLength": 1, "maxLength": 60, "examples": [ "Moon & Co" ] }, "tone": { "type": "string", "enum": [ "professional", "casual", "mystical", "playful", "formal" ] }, "audience": { "type": "string", "enum": [ "consumer", "employee", "manager", "customer", "community" ] }, "safety_mode": { "type": "string", "enum": [ "default", "workplace", "financial_wellness", "entertainment" ] } } }, "NatalChartRequest": { "allOf": [ { "type": "object", "required": [ "birth_datetime", "latitude", "longitude" ], "properties": { "birth_datetime": { "type": "string", "format": "date-time" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "house_system": { "type": "string", "enum": [ "P", "W", "K", "E" ], "default": "P" }, "interpret": { "type": "boolean", "default": false }, "language": { "type": "string", "default": "en" } } }, { "$ref": "#/components/schemas/WhiteLabelBrandFields" } ] }, "BaziRequest": { "allOf": [ { "type": "object", "description": "Accepts either legacy birth_datetime or BirthSubjectInput fields; optional white-label fields apply when interpret=true.", "properties": { "birth_datetime": { "type": "string", "format": "date-time" }, "gender": { "type": "string", "enum": [ "male", "female", "unknown" ], "default": "unknown" }, "interpret": { "type": "boolean", "default": false }, "language": { "type": "string", "enum": [ "zh", "zh-cn", "en", "th" ], "default": "zh" } } }, { "$ref": "#/components/schemas/WhiteLabelBrandFields" } ] }, "DailyHoroscopeRequest": { "type": "object", "required": [ "sign", "date" ], "properties": { "sign": { "type": "string", "enum": [ "aries", "taurus", "gemini", "cancer", "leo", "virgo", "libra", "scorpio", "sagittarius", "capricorn", "aquarius", "pisces" ] }, "date": { "type": "string", "format": "date" }, "locale": { "type": "string", "minLength": 2, "maxLength": 24, "examples": [ "th" ] } } }, "DailyHoroscopeResponse": { "type": "object", "required": [ "sign", "date", "text" ], "properties": { "sign": { "type": "string" }, "date": { "type": "string", "format": "date" }, "text": { "type": "string" }, "mood": { "type": "string" }, "lucky_number": { "type": "integer", "minimum": 1, "maximum": 99 }, "lucky_color": { "type": "string" } } }, "BaziPillar": { "type": "object", "required": [ "heavenlyStem", "earthlyBranch" ], "properties": { "heavenlyStem": { "type": "string", "examples": [ "甲" ] }, "earthlyBranch": { "type": "string", "examples": [ "子" ] } } }, "BaziResponse": { "type": "object", "required": [ "pillars", "dayMaster", "elementBalance" ], "properties": { "pillars": { "type": "object", "required": [ "year", "month", "day", "hour" ], "properties": { "year": { "$ref": "#/components/schemas/BaziPillar" }, "month": { "$ref": "#/components/schemas/BaziPillar" }, "day": { "$ref": "#/components/schemas/BaziPillar" }, "hour": { "$ref": "#/components/schemas/BaziPillar" } } }, "dayMaster": { "type": "string", "examples": [ "丙火" ] }, "elementBalance": { "type": "object", "required": [ "wood", "fire", "earth", "metal", "water" ], "properties": { "wood": { "type": "integer", "minimum": 0 }, "fire": { "type": "integer", "minimum": 0 }, "earth": { "type": "integer", "minimum": 0 }, "metal": { "type": "integer", "minimum": 0 }, "water": { "type": "integer", "minimum": 0 } } } } }, "SajuRequest": { "allOf": [ { "$ref": "#/components/schemas/BirthSubjectInput" }, { "type": "object", "properties": { "locale": { "type": "string", "minLength": 2, "maxLength": 24, "examples": [ "th" ] }, "focus": { "type": "string", "enum": [ "general", "love", "career", "wealth" ], "default": "general" }, "question": { "type": "string", "minLength": 1, "maxLength": 1000 }, "gender": { "type": "string", "enum": [ "male", "female", "unknown" ], "default": "unknown", "description": "For major luck (대운) direction: male+Yang year → forward, male+Yin → backward; female is the opposite. When unknown, direction defaults to forward with direction_assumed_default on the response." }, "annual_luck_years_before": { "type": "integer", "minimum": 0, "maximum": 80, "description": "How many civil calendar years before the birth UTC calendar year to include in annual_luck (流年). Default 5; total row count capped at 121 years." }, "annual_luck_years_after": { "type": "integer", "minimum": 0, "maximum": 80, "description": "Civil years after birth UTC year in annual_luck. Default 20." } } } ] }, "SajuMajorLuckPeriod": { "type": "object", "required": [ "index", "stem", "branch", "stem_en", "branch_en", "animal", "stem_element", "branch_element", "hidden_stems", "stem_ten_god", "approximate_start_utc", "approximate_end_utc_exclusive" ], "properties": { "index": { "type": "integer", "minimum": 0 }, "stem": { "type": "string" }, "branch": { "type": "string" }, "stem_en": { "type": "string" }, "branch_en": { "type": "string" }, "animal": { "type": "string" }, "stem_element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] }, "branch_element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] }, "hidden_stems": { "type": "array", "items": { "$ref": "#/components/schemas/SajuHiddenStem" } }, "stem_ten_god": { "$ref": "#/components/schemas/SajuTenGod" }, "approximate_start_utc": { "type": "string", "format": "date-time" }, "approximate_end_utc_exclusive": { "type": "string", "format": "date-time" } } }, "SajuMajorLuck": { "type": "object", "required": [ "direction", "direction_korean", "gender_input", "direction_assumed_default", "approximate_timescale_note", "periods" ], "properties": { "direction": { "type": "string", "enum": [ "forward", "backward" ] }, "direction_korean": { "type": "string", "enum": [ "순행", "역행" ] }, "gender_input": { "type": "string", "enum": [ "male", "female", "unknown" ] }, "direction_assumed_default": { "type": "boolean" }, "approximate_timescale_note": { "type": "string" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/SajuMajorLuckPeriod" }, "minItems": 8, "maxItems": 8 } } }, "SajuAnnualYear": { "type": "object", "required": [ "civil_year", "stem", "branch", "stem_en", "branch_en", "animal", "stem_element", "branch_element", "hidden_stems", "stem_ten_god" ], "properties": { "civil_year": { "type": "integer" }, "stem": { "type": "string" }, "branch": { "type": "string" }, "stem_en": { "type": "string" }, "branch_en": { "type": "string" }, "animal": { "type": "string" }, "stem_element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] }, "branch_element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] }, "hidden_stems": { "type": "array", "items": { "$ref": "#/components/schemas/SajuHiddenStem" } }, "stem_ten_god": { "$ref": "#/components/schemas/SajuTenGod" } } }, "SajuAnnualLuck": { "type": "object", "required": [ "anchor_civil_year_utc", "years_before", "years_after", "approximate_calendar_note", "years" ], "properties": { "anchor_civil_year_utc": { "type": "integer", "description": "UTC calendar year of the normalized birth instant" }, "years_before": { "type": "integer", "minimum": 0, "maximum": 80 }, "years_after": { "type": "integer", "minimum": 0, "maximum": 80 }, "approximate_calendar_note": { "type": "string" }, "years": { "type": "array", "items": { "$ref": "#/components/schemas/SajuAnnualYear" }, "minItems": 1, "maxItems": 121 } } }, "SajuPillar": { "type": "object", "required": [ "stem", "branch", "stem_en", "branch_en", "animal", "stem_element", "branch_element" ], "properties": { "stem": { "type": "string" }, "branch": { "type": "string" }, "stem_en": { "type": "string" }, "branch_en": { "type": "string" }, "animal": { "type": "string" }, "stem_element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] }, "branch_element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] } } }, "SajuTenGod": { "type": "object", "required": [ "name", "korean", "relation" ], "properties": { "name": { "type": "string" }, "korean": { "type": "string" }, "relation": { "type": "string" } } }, "SajuHiddenStem": { "type": "object", "required": [ "stem", "element" ], "properties": { "stem": { "type": "string" }, "element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] } } }, "SajuBranchInteraction": { "type": "object", "required": [ "type", "korean", "branches", "pillars", "description" ], "properties": { "type": { "type": "string", "enum": [ "clash", "combination" ] }, "korean": { "type": "string", "enum": [ "충", "육합" ] }, "branches": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 }, "pillars": { "type": "array", "items": { "type": "string", "enum": [ "year", "month", "day", "hour" ] }, "minItems": 2, "maxItems": 2 }, "description": { "type": "string" } } }, "SajuResponse": { "type": "object", "required": [ "system", "pillars", "day_master", "five_elements", "hidden_stems", "branch_interactions", "ten_gods", "major_luck", "annual_luck", "focus", "question", "reading_summary" ], "properties": { "system": { "type": "string", "const": "korean_saju" }, "pillars": { "type": "object", "required": [ "year", "month", "day", "hour" ], "properties": { "year": { "$ref": "#/components/schemas/SajuPillar" }, "month": { "$ref": "#/components/schemas/SajuPillar" }, "day": { "$ref": "#/components/schemas/SajuPillar" }, "hour": { "$ref": "#/components/schemas/SajuPillar" } } }, "day_master": { "type": "object", "required": [ "stem", "element", "polarity", "korean", "strength" ], "properties": { "stem": { "type": "string" }, "element": { "type": "string", "enum": [ "Wood", "Fire", "Earth", "Metal", "Water" ] }, "polarity": { "type": "string", "enum": [ "Yin", "Yang" ] }, "korean": { "type": "string", "const": "일간" }, "strength": { "type": "string", "enum": [ "weak", "balanced", "strong" ] } } }, "five_elements": { "type": "object", "required": [ "counts", "balance" ], "properties": { "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "balance": { "type": "object", "required": [ "strongest", "missing", "favorable" ], "properties": { "strongest": { "type": "array", "items": { "type": "string" } }, "missing": { "type": "array", "items": { "type": "string" } }, "favorable": { "type": "string" } } } } }, "hidden_stems": { "type": "object", "required": [ "year", "month", "day", "hour" ], "properties": { "year": { "type": "array", "items": { "$ref": "#/components/schemas/SajuHiddenStem" } }, "month": { "type": "array", "items": { "$ref": "#/components/schemas/SajuHiddenStem" } }, "day": { "type": "array", "items": { "$ref": "#/components/schemas/SajuHiddenStem" } }, "hour": { "type": "array", "items": { "$ref": "#/components/schemas/SajuHiddenStem" } } } }, "branch_interactions": { "type": "array", "items": { "$ref": "#/components/schemas/SajuBranchInteraction" } }, "ten_gods": { "type": "object", "required": [ "year_stem", "month_stem", "day_stem", "hour_stem" ], "properties": { "year_stem": { "$ref": "#/components/schemas/SajuTenGod" }, "month_stem": { "$ref": "#/components/schemas/SajuTenGod" }, "day_stem": { "$ref": "#/components/schemas/SajuTenGod" }, "hour_stem": { "$ref": "#/components/schemas/SajuTenGod" } } }, "major_luck": { "$ref": "#/components/schemas/SajuMajorLuck" }, "annual_luck": { "$ref": "#/components/schemas/SajuAnnualLuck" }, "focus": { "type": "string", "enum": [ "general", "love", "career", "wealth" ] }, "question": { "type": [ "string", "null" ] }, "reading_summary": { "type": "string", "minLength": 1 } } }, "PanchangRequest": { "type": "object", "required": [ "date", "latitude", "longitude", "timezoneOffsetMinutes" ], "properties": { "date": { "type": "string", "format": "date" }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 }, "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "timezoneOffsetMinutes": { "type": "integer", "minimum": -840, "maximum": 840 } } }, "PanchangResponse": { "type": "object", "required": [ "tithi", "nakshatra", "yoga", "karana", "sunrise", "sunset", "moon_phase", "moon_phase_th" ], "properties": { "tithi": { "type": "object", "required": [ "name", "name_th", "number", "paksha" ], "properties": { "name": { "type": "string" }, "name_th": { "type": "string" }, "number": { "type": "integer", "minimum": 1, "maximum": 30 }, "paksha": { "type": "string", "enum": [ "shukla", "krishna" ] } } }, "nakshatra": { "type": "object", "required": [ "name", "name_th", "lord", "lord_th" ], "properties": { "name": { "type": "string" }, "name_th": { "type": "string" }, "lord": { "type": "string" }, "lord_th": { "type": "string" } } }, "yoga": { "$ref": "#/components/schemas/LocalizedName" }, "karana": { "$ref": "#/components/schemas/LocalizedName" }, "sunrise": { "type": "string", "examples": [ "06:05" ] }, "sunset": { "type": "string", "examples": [ "18:32" ] }, "moon_phase": { "type": "string" }, "moon_phase_th": { "type": "string" }, "snapshot_instant_note": { "type": "string" }, "sun_time_calculation": { "type": "string", "enum": [ "rise_trans", "geometric_approx", "polar_placeholder" ] } } }, "LocalizedName": { "type": "object", "required": [ "name", "name_th" ], "properties": { "name": { "type": "string" }, "name_th": { "type": "string" } } }, "TarotDailyRequest": { "type": "object", "required": [ "date" ], "properties": { "date": { "type": "string", "format": "date" }, "locale": { "type": "string", "minLength": 2, "maxLength": 24, "examples": [ "th" ] } } }, "TarotDailyResponse": { "type": "object", "required": [ "orientation", "card", "keywords", "keywords_th", "upright", "reversed" ], "properties": { "orientation": { "type": "string", "enum": [ "upright", "reversed" ] }, "card": { "type": "object", "required": [ "id", "name", "name_th", "suit", "arcana" ], "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 77 }, "name": { "type": "string" }, "name_th": { "type": "string" }, "suit": { "type": "string" }, "arcana": { "type": "string", "enum": [ "major", "minor" ] } } }, "keywords": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 }, "keywords_th": { "type": "array", "items": { "type": "string" }, "minItems": 2, "maxItems": 2 }, "upright": { "type": "string" }, "reversed": { "type": "string" } } }, "TarotSpreadRequest": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "minLength": 1, "maxLength": 4096 }, "locale": { "type": "string", "minLength": 2, "maxLength": 24, "examples": [ "th" ] }, "brand_name": { "type": "string", "minLength": 1, "maxLength": 60, "examples": [ "Moon & Co" ] }, "tone": { "type": "string", "enum": [ "professional", "casual", "mystical", "playful", "formal" ] }, "audience": { "type": "string", "enum": [ "consumer", "employee", "manager", "customer", "community" ] }, "safety_mode": { "type": "string", "enum": [ "default", "workplace", "financial_wellness", "entertainment" ] } } }, "TarotSpreadResponse": { "type": "object", "required": [ "cards", "reading_summary" ], "properties": { "cards": { "type": "array", "items": { "$ref": "#/components/schemas/TarotSpreadCard" }, "minItems": 3 }, "reading_summary": { "type": "string", "minLength": 1 } } }, "TarotSpreadCard": { "type": "object", "required": [ "position", "card_id", "card_name", "card_name_th", "upright", "keywords", "keywords_th", "meaning" ], "properties": { "position": { "type": "string" }, "card_id": { "type": "integer", "minimum": 0, "maximum": 77 }, "card_name": { "type": "string" }, "card_name_th": { "type": "string" }, "upright": { "type": "boolean" }, "keywords": { "type": "array", "items": { "type": "string" } }, "keywords_th": { "type": "array", "items": { "type": "string" } }, "meaning": { "type": "string", "minLength": 1 } } }, "VimshottariResponse": { "type": "object", "required": [ "periods" ], "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/DashaPeriod" }, "minItems": 9, "maxItems": 9 } } }, "DashaPeriod": { "type": "object", "required": [ "planet", "planet_th", "startDate", "endDate", "subPeriods" ], "properties": { "planet": { "type": "string" }, "planet_th": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" }, "subPeriods": { "type": "array", "items": { "type": "object", "required": [ "planet", "planet_th", "startDate", "endDate" ], "properties": { "planet": { "type": "string" }, "planet_th": { "type": "string" }, "startDate": { "type": "string", "format": "date" }, "endDate": { "type": "string", "format": "date" } } }, "minItems": 9, "maxItems": 9 } } }, "ManglikResponse": { "type": "object", "required": [ "has_dosha", "severity", "description", "remedies" ], "properties": { "has_dosha": { "type": "boolean" }, "severity": { "type": "string", "enum": [ "none", "low", "medium", "high" ] }, "description": { "type": "string" }, "remedies": { "type": "array", "items": { "type": "string" } } } }, "SadeSatiResponse": { "type": "object", "required": [ "has_sade_sati", "currentPhase", "phaseDescription", "startDate", "endDate", "remedies" ], "properties": { "has_sade_sati": { "type": "boolean" }, "currentPhase": { "oneOf": [ { "type": "integer", "enum": [ 1, 2, 3 ] }, { "type": "null" } ] }, "phaseDescription": { "type": "string" }, "startDate": { "type": [ "string", "null" ], "format": "date" }, "endDate": { "type": [ "string", "null" ], "format": "date" }, "remedies": { "type": "array", "items": { "type": "string" } } } }, "NumerologyCoreRequest": { "type": "object", "required": [ "full_name", "birth_date" ], "properties": { "full_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "birth_date": { "type": "string", "format": "date" }, "locale": { "type": "string", "enum": [ "en", "th" ] } } }, "NumerologyCoreResponse": { "type": "object", "required": [ "lifePathNumber", "expressionNumber", "soulUrgeNumber", "personalityNumber", "birthdayNumber" ], "properties": { "lifePathNumber": { "type": "integer" }, "expressionNumber": { "type": "integer" }, "soulUrgeNumber": { "type": "integer" }, "personalityNumber": { "type": "integer" }, "birthdayNumber": { "type": "integer" }, "th": { "type": "object", "additionalProperties": true } } }, "KundliMatchingRequest": { "type": "object", "required": [ "boy", "girl" ], "properties": { "boy": { "$ref": "#/components/schemas/BirthSubjectInput" }, "girl": { "$ref": "#/components/schemas/BirthSubjectInput" } } }, "KundliMatchingResponse": { "type": "object", "required": [ "totalPoints", "maximumPoints", "components", "doshas", "recommendation" ], "properties": { "totalPoints": { "type": "number", "minimum": 0, "maximum": 36 }, "maximumPoints": { "type": "number", "const": 36 }, "components": { "type": "array", "items": { "type": "object", "required": [ "name", "points", "maxPoints", "description" ], "properties": { "name": { "type": "string" }, "points": { "type": "number" }, "maxPoints": { "type": "number" }, "description": { "type": "string" } } }, "minItems": 8, "maxItems": 8 }, "doshas": { "type": "object", "additionalProperties": true }, "recommendation": { "type": "string" } } }, "CompatibilityRequest": { "type": "object", "required": [ "person_a", "person_b" ], "properties": { "person_a": { "$ref": "#/components/schemas/BirthSubjectInput" }, "person_b": { "$ref": "#/components/schemas/BirthSubjectInput" }, "systems": { "type": "array", "items": { "type": "string", "enum": [ "western", "bazi", "thai" ] }, "description": "Subset of systems to evaluate. Defaults to all three when omitted." }, "locale": { "type": "string", "enum": [ "th", "en" ] } } }, "CompatibilityResponse": { "type": "object", "required": [ "overall_score", "overall_label_th", "overall_label_en", "systems_included", "western", "bazi", "thai" ], "properties": { "overall_score": { "type": "number", "minimum": 0, "maximum": 100 }, "overall_label_th": { "type": "string" }, "overall_label_en": { "type": "string" }, "systems_included": { "type": "array", "items": { "type": "string", "enum": [ "western", "bazi", "thai" ] } }, "western": { "nullable": true, "type": "object", "required": [ "score", "aspects", "summary_th", "summary_en" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "aspects": { "type": "array", "items": { "type": "object", "required": [ "planet_a", "planet_b", "aspect", "orb_degrees", "is_harmonious", "weight" ], "properties": { "planet_a": { "type": "string", "enum": [ "sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn" ] }, "planet_b": { "type": "string", "enum": [ "sun", "moon", "mercury", "venus", "mars", "jupiter", "saturn" ] }, "aspect": { "type": "string", "enum": [ "conjunction", "sextile", "square", "trine", "opposition" ] }, "orb_degrees": { "type": "number", "minimum": 0 }, "is_harmonious": { "type": "boolean" }, "weight": { "type": "number", "minimum": 0, "maximum": 1 } } } }, "summary_th": { "type": "string" }, "summary_en": { "type": "string" } } }, "bazi": { "nullable": true, "type": "object", "required": [ "score", "day_master_a", "day_master_b", "element_relationship", "summary_th", "summary_en" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "day_master_a": { "type": "object", "required": [ "stem_th", "stem_en", "element" ], "properties": { "stem_th": { "type": "string" }, "stem_en": { "type": "string" }, "element": { "type": "string", "enum": [ "wood", "fire", "earth", "metal", "water" ] } } }, "day_master_b": { "type": "object", "required": [ "stem_th", "stem_en", "element" ], "properties": { "stem_th": { "type": "string" }, "stem_en": { "type": "string" }, "element": { "type": "string", "enum": [ "wood", "fire", "earth", "metal", "water" ] } } }, "element_relationship": { "type": "string", "enum": [ "producing_a_to_b", "producing_b_to_a", "controlling_a_to_b", "controlling_b_to_a", "same" ] }, "summary_th": { "type": "string" }, "summary_en": { "type": "string" } } }, "thai": { "nullable": true, "type": "object", "required": [ "score", "zodiac_a", "zodiac_b", "relationship", "label_th", "label_en", "summary_th", "summary_en" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100 }, "zodiac_a": { "type": "object", "required": [ "animal_th", "animal_en", "year" ], "properties": { "animal_th": { "type": "string" }, "animal_en": { "type": "string" }, "year": { "type": "integer" } } }, "zodiac_b": { "type": "object", "required": [ "animal_th", "animal_en", "year" ], "properties": { "animal_th": { "type": "string" }, "animal_en": { "type": "string" }, "year": { "type": "integer" } } }, "relationship": { "type": "string", "enum": [ "trine", "compatible", "neutral", "clash" ] }, "label_th": { "type": "string" }, "label_en": { "type": "string" }, "summary_th": { "type": "string" }, "summary_en": { "type": "string" } } } } }, "MuhurtaResponse": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "buddhist_date": { "type": "string" }, "weekday": { "type": "string", "enum": [ "sun", "mon", "tue", "wed", "thu", "fri", "sat" ] }, "sunrise": { "type": "string", "example": "06:00" }, "sunset": { "type": "string", "example": "18:00" }, "rahu_kalam": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } } }, "best_windows": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "string", "example": "13:00" }, "end_time": { "type": "string", "example": "14:00" }, "score": { "type": "number", "minimum": 0, "maximum": 100 }, "factors": { "type": "object", "properties": { "tithi": { "type": "object", "properties": { "number": { "type": "integer" }, "class": { "type": "string", "enum": [ "Nanda", "Bhadra", "Jaya", "Rikta", "Purna" ] }, "score": { "type": "number" } } }, "nakshatra": { "type": "object", "properties": { "name_th": { "type": "string" }, "class": { "type": "integer", "minimum": 1, "maximum": 9 }, "score": { "type": "number" } } }, "hora": { "type": "object", "properties": { "planet": { "type": "string", "enum": [ "sun", "moon", "mars", "mercury", "jupiter", "venus", "saturn" ] }, "score": { "type": "number" } } }, "lagna": { "type": "object", "properties": { "sign": { "type": "string" }, "sign_th": { "type": "string" }, "score": { "type": "number" } } } } }, "in_rahu_kalam": { "type": "boolean" }, "rationale_th": { "type": "string" }, "rationale_en": { "type": "string" } } } } } }, "UranianBaseRequest": { "type": "object", "required": [ "birth_date", "birth_time", "birth_lat", "birth_lon" ], "properties": { "birth_date": { "type": "string", "format": "date", "example": "1990-05-15" }, "birth_time": { "type": "string", "pattern": "^d{2}:d{2}$", "example": "14:30" }, "birth_lat": { "type": "number", "minimum": -90, "maximum": 90 }, "birth_lon": { "type": "number", "minimum": -180, "maximum": 180 }, "birth_place": { "type": "string", "minLength": 1, "maxLength": 200 }, "dial_mode": { "type": "number", "enum": [ 90, 45, 22.5 ], "default": 90 }, "orb_max": { "type": "number", "minimum": 0.25, "maximum": 3, "default": 1 } } }, "UranianMeta": { "type": "object", "required": [ "dial_mode", "orb_max", "computed_at" ], "properties": { "dial_mode": { "type": "number", "enum": [ 90, 45, 22.5 ] }, "orb_max": { "type": "number" }, "computed_at": { "type": "string", "format": "date-time" } } }, "UranianPosition": { "type": "object", "required": [ "name", "category", "longitude", "dial_position", "is_hamburg" ], "properties": { "name": { "type": "string" }, "category": { "type": "string", "enum": [ "traditional", "hamburg", "personal_point" ] }, "longitude": { "type": "number", "minimum": 0, "maximum": 360 }, "dial_position": { "type": "number" }, "is_hamburg": { "type": "boolean" } } }, "UranianMidpoint": { "type": "object", "required": [ "pair", "longitude", "dial_position" ], "properties": { "pair": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "string" } ], "minItems": 2, "maxItems": 2 }, "longitude": { "type": "number" }, "dial_position": { "type": "number" }, "interpretation_en": { "type": "string" }, "interpretation_th": { "type": "string" } } }, "UranianPlanetaryPicture": { "type": "object", "required": [ "factors", "dial_position", "orb_total", "interpretation_key", "interpretation_en", "interpretation_th" ], "properties": { "factors": { "type": "array", "items": { "type": "string" } }, "dial_position": { "type": "number" }, "orb_total": { "type": "number" }, "interpretation_key": { "type": "string" }, "interpretation_en": { "type": "string" }, "interpretation_th": { "type": "string" } } }, "UranianChartResponse": { "type": "object", "required": [ "birth_place", "meta", "positions", "midpoints", "planetary_pictures" ], "properties": { "birth_place": { "type": [ "string", "null" ] }, "meta": { "$ref": "#/components/schemas/UranianMeta" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/UranianPosition" }, "minItems": 22, "maxItems": 22 }, "midpoints": { "type": "array", "items": { "$ref": "#/components/schemas/UranianMidpoint" }, "minItems": 153 }, "planetary_pictures": { "type": "array", "items": { "$ref": "#/components/schemas/UranianPlanetaryPicture" } } } }, "UranianMidpointsResponse": { "type": "object", "required": [ "birth_place", "meta", "anchor", "midpoints" ], "properties": { "birth_place": { "type": [ "string", "null" ] }, "meta": { "$ref": "#/components/schemas/UranianMeta" }, "anchor": { "type": "string" }, "midpoints": { "type": "array", "items": { "$ref": "#/components/schemas/UranianMidpoint" } } } }, "UranianPicturesResponse": { "type": "object", "required": [ "birth_place", "meta", "life_area", "relevant_factors", "pictures" ], "properties": { "birth_place": { "type": [ "string", "null" ] }, "meta": { "$ref": "#/components/schemas/UranianMeta" }, "life_area": { "type": "string", "enum": [ "career", "love", "money", "health", "family", "spiritual" ] }, "relevant_factors": { "type": "array", "items": { "type": "string" } }, "pictures": { "type": "array", "items": { "$ref": "#/components/schemas/UranianPlanetaryPicture" } } } }, "CulturalOrgCreateRequest": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string" }, "contact_email": { "type": "string", "format": "email" }, "default_locale": { "type": "string", "enum": ["th", "en"], "default": "th" }, "default_market": { "type": "string", "default": "TH" }, "monthly_unit_quota": { "type": "integer", "default": 10000 } } }, "CulturalOrg": { "type": "object", "required": ["org_id", "name", "default_locale", "default_market", "status", "quota_mode", "monthly_unit_quota", "units_used_current_period"], "properties": { "org_id": { "type": "string" }, "owner_user_id": { "type": "integer" }, "name": { "type": "string" }, "contact_email": { "type": ["string", "null"] }, "default_locale": { "type": "string", "enum": ["th", "en"] }, "default_market": { "type": "string" }, "status": { "type": "string", "enum": ["active", "suspended"] }, "quota_mode": { "type": "string", "enum": ["shared"] }, "monthly_unit_quota": { "type": "integer" }, "units_used_current_period": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CulturalProfileCreateRequest": { "type": "object", "required": ["birth_date", "birth_time", "birth_lat", "birth_lng", "birth_timezone_offset_minutes"], "properties": { "external_id": { "type": "string" }, "profile_type": { "type": "string", "enum": ["employee", "member", "customer", "community_user", "candidate", "synthetic"], "default": "employee" }, "birth_date": { "type": "string", "format": "date" }, "birth_time": { "type": "string", "example": "08:30" }, "birth_lat": { "type": "number", "minimum": -90, "maximum": 90 }, "birth_lng": { "type": "number", "minimum": -180, "maximum": 180 }, "birth_timezone_offset_minutes": { "type": "integer" }, "birth_city": { "type": "string" }, "locale": { "type": "string", "enum": ["th", "en"], "default": "th" }, "market": { "type": "string", "default": "TH" }, "tags": { "type": "array", "items": { "type": "string" } }, "consent_basis": { "type": "string" } } }, "CulturalProfile": { "type": "object", "description": "Public profile metadata. Raw and encrypted birth fields are intentionally omitted.", "required": ["profile_id", "org_id", "profile_type", "status", "locale", "market", "tags"], "properties": { "profile_id": { "type": "string" }, "org_id": { "type": "string" }, "external_id": { "type": ["string", "null"] }, "profile_type": { "type": "string" }, "status": { "type": "string", "enum": ["active", "deleted"] }, "locale": { "type": "string", "enum": ["th", "en"] }, "market": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "consent_basis": { "type": ["string", "null"] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": ["string", "null"], "format": "date-time" } } }, "CulturalReadingEnvelope": { "type": "object", "required": ["org_id", "locale", "market", "content", "guardrails", "meta"], "properties": { "org_id": { "type": "string" }, "profile_id": { "type": "string" }, "locale": { "type": "string" }, "market": { "type": "string" }, "content": { "type": "object", "required": ["title", "summary", "reflection_prompt", "suggested_action", "theme"], "properties": { "title": { "type": "string" }, "summary": { "type": "string" }, "reflection_prompt": { "type": "string" }, "suggested_action": { "type": "string" }, "share_text": { "type": "string" }, "theme": { "type": "string" }, "confidence_style": { "type": "string" } } }, "guardrails": { "$ref": "#/components/schemas/CulturalGuardrails" }, "meta": { "$ref": "#/components/schemas/CulturalMeta" } } }, "CulturalGuardrails": { "type": "object", "required": ["allowed_use", "prohibited_use_notice"], "properties": { "allowed_use": { "type": "string" }, "prohibited_use_notice": { "type": "string" } } }, "CulturalMeta": { "type": "object", "required": ["engine", "endpoint_family", "units_charged", "generated_at"], "properties": { "engine": { "type": "string" }, "endpoint_family": { "type": "string" }, "units_charged": { "type": "integer" }, "generated_at": { "type": "string", "format": "date-time" } } }, "CulturalTeamReflection": { "type": "object", "required": ["org_id", "team_id", "element_balance", "content", "guardrails", "meta"], "properties": { "org_id": { "type": "string" }, "team_id": { "type": "string" }, "element_balance": { "type": "object", "additionalProperties": { "type": "integer" } }, "content": { "type": "object" }, "guardrails": { "$ref": "#/components/schemas/CulturalGuardrails" }, "meta": { "$ref": "#/components/schemas/CulturalMeta" } } }, "CulturalCampaignRequest": { "type": "object", "properties": { "theme": { "type": "string" }, "market": { "type": "string" }, "segment_id": { "type": "string" } } }, "CulturalCampaignResponse": { "type": "object", "required": ["org_id", "theme", "content", "meta"], "properties": { "org_id": { "type": "string" }, "segment_id": { "type": ["string", "null"] }, "market": { "type": "string" }, "theme": { "type": "string" }, "content": { "type": "object", "required": ["push_copy", "card_copy", "long_copy", "compliance_note"], "properties": { "push_copy": { "type": "string" }, "card_copy": { "type": "string" }, "long_copy": { "type": "string" }, "compliance_note": { "type": "string" } } }, "meta": { "$ref": "#/components/schemas/CulturalMeta" } } }, "CulturalUsageSummary": { "type": "object", "required": ["org_id", "period", "quota_mode", "monthly_unit_quota", "units_used_current_period", "by_endpoint", "by_family"], "properties": { "org_id": { "type": "string" }, "period": { "type": "string" }, "quota_mode": { "type": "string" }, "monthly_unit_quota": { "type": "integer" }, "units_used_current_period": { "type": "integer" }, "by_endpoint": { "type": "object", "additionalProperties": { "type": "integer" } }, "by_family": { "type": "object", "additionalProperties": { "type": "integer" } } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" }, "example": { "error": "unauthorized", "message": "Invalid API key", "code": "401", "request_id": "01HQXYZ..." } } } }, "PaymentRequired": { "description": "Insufficient credits (checked before work where applicable; deduction is atomic)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" }, "example": { "error": "payment_required", "message": "Insufficient credits for this request", "code": "402", "request_id": "01HQXYZ..." } } } }, "NotFound": { "description": "Resource not available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" } } } }, "InternalError": { "description": "Unexpected failure — body omits stack traces; check logs with request_id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" }, "example": { "error": "internal_server_error", "message": "Could not compute Panchang.", "code": "internal", "request_id": "01HQXYZ..." } } } }, "BadGatewayInterpretation": { "description": "LLM returned unusable structured output (no billing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" }, "example": { "error": "bad_gateway", "message": "Tarot interpretation could not be parsed; please retry.", "code": "interpretation_malformed", "request_id": "01HQXYZ..." } } } }, "ServiceUnavailableInterpretation": { "description": "Interpretation provider not configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonError" }, "example": { "error": "service_unavailable", "message": "Tarot interpretation is not configured (missing ANTHROPIC_API_KEY).", "code": "interpretation_unavailable", "request_id": "01HQXYZ..." } } } } } } }