{ "openapi": "3.1.1", "info": { "title": "Cosmic Ephemeris supplemental symbolic API", "version": "1.1.0", "description": "Supplemental APIs for Tarot, fact-linked readings and explicit Vedic/calendar systems. MCP exposes these through cosmicephemeris_symbolic, separately from the 78-operation calculation tool. Published Node/Python 0.5.0 includes typed methods. Readings and translations are AI-assisted symbolic reflections. One standard credit per admitted attempt, including calculation failures. No account persistence, signed receipts, batch jobs or external AI provider." }, "servers": [ { "url": "https://api.cosmicephemeris.com" } ], "security": [ { "BearerApiKey": [] }, { "HeaderApiKey": [] } ], "paths": { "/api/symbolic/tarot": { "post": { "operationId": "drawTarotReading", "summary": "Generate a translated Tarot reading", "x-required-scope": "astro:tarot", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TarotRequest" }, "example": { "locale": "es", "options": { "spread": "three", "theme": "relationship", "reversals": true, "mode": "draw" } } } } }, "responses": { "200": { "description": "Server-generated reading; no account record is saved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reading" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/api/symbolic/symbolic-reading": { "post": { "operationId": "generateSymbolicReading", "summary": "Generate a fact-linked symbolic reading", "x-required-scope": "astro:symbolic-reading", "description": "Birth, compatibility, numerology or sampled ongoing themes in en/es/hi. Whole-sign houses. Vedic requires explicit ayanamsa. Ongoing historical start_date uses explicit calendar at noon UT1; standard strings use noon UTC within 1800–2200. Annual samples are first-of-month within the chosen calendar year; weekly samples must all remain in range. Vedic compatibility requires both births in the same time mode. Historical numerology requires an explicit year_convention.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SymbolicRequest" } } } }, "responses": { "200": { "description": "Reading with original calculation evidence and symbolic-use disclosures.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reading" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } }, "/api/symbolic/vedic-systems": { "post": { "operationId": "calculateSupplementalVedicSystem", "summary": "Calculate Yogini, birth factors, regional factors or named festival calendars", "x-required-scope": "astro:vedic-systems", "description": "Explicit named models, not every regional or sectarian convention. festival_calendar requires region north_purnimanta or south_amanta, days 1–31, explicit lahiri ayanamsa and birth/date/location/timezone. Version north_south_named_observances_v3 has eighteen named observances per preset. Original seven retain sunrise/midday/afternoon maximum-overlap and earlier-tie conventions. Eight additions (Vasant Panchami, Ratha Saptami, Maha Shivaratri, Buddha Purnima, Dhanteras, Diwali/Lakshmi Puja, Bhai Dooj, Kartik Purnima) require a unique governing day; multiple/absent windows return unresolved_observances, not guessed dates. Purvahna is the first half of daylight, Pradosha the first fifth of sunset to next sunrise, Nishita its middle fifteenth; nights belong to the sunset date. Results expose governing-window evidence, not ritual muhurta. Annual rules exclude adhika; kshaya and Purnimanta intercalation remain unresolved. Three further rules add Holika Dahan (Bhadra-free Pradosha, or after Bhadra before Hindu midnight when Purnima overlaps Pradosha), next-day Holi derived only from resolved Holika, and Raksha Bandhan (Bhadra-free Aparahna, then Pradosha). Bhadra ends at solved 174-degree elongation. Holi returns source_observance and an offset rule instead of its own governing-window/tithi timestamps. metadata.coverage declares exclusions: Holika Bhadra-tail/face and Raksha overnight exceptions, Janmashtami, Ekadashi/parana, solar-ingress and temple festivals. Not complete regional coverage. Historical dates are proleptic, not evidence of observance.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "birth", "ayanamsa", "system" ], "properties": { "birth": { "$ref": "#/components/schemas/Birth" }, "ayanamsa": { "$ref": "#/components/schemas/Ayanamsa" }, "system": { "enum": [ "yogini", "birth_factors", "regional_calendars" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "birth", "ayanamsa", "system", "region", "days" ], "properties": { "birth": { "$ref": "#/components/schemas/Birth" }, "ayanamsa": { "const": "lahiri" }, "system": { "const": "festival_calendar" }, "region": { "enum": [ "north_purnimanta", "south_amanta" ] }, "days": { "type": "integer", "minimum": 1, "maximum": 31 } } } ] }, "example": { "birth": { "date": "2000-01-01", "time": "12:00", "timezone": "UTC", "lat": 28.6, "lon": 77.2 }, "ayanamsa": "lahiri", "system": "yogini" } } } }, "responses": { "200": { "description": "Calculated system with explicit input, method metadata, warnings and type-dependent results.", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "input", "metadata" ], "properties": { "type": { "enum": [ "yogini", "birth_factors", "regional_calendars", "festival_calendar" ] }, "input": { "type": "object" }, "metadata": { "type": "object" }, "yogini": { "type": "object" }, "moon_nakshatra": { "type": "object" }, "navamsa": { "type": "object" }, "national_calendar": { "type": "object" }, "lunar_months": { "type": "object" }, "days": { "type": "array", "items": { "type": "object" } }, "festivals": { "type": "array", "items": { "type": "object" } }, "unresolved_observances": { "type": "array", "items": { "type": "object" } }, "supported_festivals": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" }, "504": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "BearerApiKey": { "type": "http", "scheme": "bearer" }, "HeaderApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "responses": { "Error": { "description": "Request, authentication, scope, quota or capacity rejection. Failed admitted attempts retain their reserved unit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } } } } }, "schemas": { "Locale": { "enum": [ "en", "es", "hi" ] }, "Ayanamsa": { "enum": [ "lahiri", "raman", "krishnamurti", "fagan_bradley", "yukteshwar", "sassanian", "true_chitra", "true_revati", "true_pushya", "galactic_center_0_sagittarius", "galactic_alignment_mardyks" ] }, "Birth": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "date", "time", "timezone", "lat", "lon" ], "properties": { "date": { "$ref": "openapi.json#/components/schemas/Date" }, "time": { "$ref": "openapi.json#/components/schemas/Time" }, "timezone": { "$ref": "openapi.json#/components/schemas/Timezone" }, "lat": { "$ref": "openapi.json#/components/schemas/Latitude" }, "lon": { "$ref": "openapi.json#/components/schemas/Longitude" } } }, { "$ref": "openapi.json#/components/schemas/HistoricalBirthInput" } ] }, "SampleDate": { "oneOf": [ { "type": "string", "format": "date", "description": "Gregorian 1800–2200, sampled at 12:00 UTC." }, { "$ref": "openapi.json#/components/schemas/HistoricalDate" } ] }, "TarotRequest": { "type": "object", "additionalProperties": false, "required": [ "locale", "options" ], "properties": { "locale": { "$ref": "#/components/schemas/Locale" }, "options": { "type": "object", "additionalProperties": false, "required": [ "spread", "theme", "reversals", "mode" ], "properties": { "spread": { "enum": [ "single", "three", "celtic_cross" ] }, "theme": { "enum": [ "general", "relationship", "career" ] }, "reversals": { "type": "boolean" }, "mode": { "enum": [ "draw", "daily" ] }, "date": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" } }, "allOf": [ { "if": { "properties": { "mode": { "const": "daily" } } }, "then": { "required": [ "date" ], "properties": { "spread": { "const": "single" } } }, "else": { "not": { "required": [ "date" ] } } } ] } } }, "SymbolicRequest": { "type": "object", "additionalProperties": false, "required": [ "kind" ], "properties": { "kind": { "enum": [ "birth", "compatibility", "numerology", "ongoing" ] }, "locale": { "$ref": "#/components/schemas/Locale" }, "birth": { "$ref": "#/components/schemas/Birth" }, "second_birth": { "$ref": "#/components/schemas/Birth" }, "tradition": { "enum": [ "western", "vedic" ] }, "ayanamsa": { "$ref": "#/components/schemas/Ayanamsa" }, "period": { "enum": [ "daily", "weekly", "annual" ] }, "start_date": { "$ref": "#/components/schemas/SampleDate" }, "numerology": { "oneOf": [ { "$ref": "openapi.json#/components/schemas/NumerologyRequest" }, { "$ref": "openapi.json#/components/schemas/HistoricalNumerologyRequest" } ] } }, "allOf": [ { "if": { "properties": { "kind": { "const": "numerology" } } }, "then": { "required": [ "numerology" ], "not": { "anyOf": [ { "required": [ "birth" ] }, { "required": [ "second_birth" ] }, { "required": [ "tradition" ] }, { "required": [ "ayanamsa" ] }, { "required": [ "period" ] }, { "required": [ "start_date" ] } ] } }, "else": { "required": [ "birth", "tradition" ], "not": { "required": [ "numerology" ] }, "allOf": [ { "if": { "properties": { "tradition": { "const": "vedic" } } }, "then": { "required": [ "ayanamsa" ] }, "else": { "not": { "required": [ "ayanamsa" ] } } } ] } }, { "if": { "properties": { "kind": { "const": "compatibility" } } }, "then": { "required": [ "second_birth" ] }, "else": { "not": { "required": [ "second_birth" ] } } }, { "if": { "properties": { "kind": { "const": "ongoing" } } }, "then": { "required": [ "period", "start_date" ] }, "else": { "not": { "anyOf": [ { "required": [ "period" ] }, { "required": [ "start_date" ] } ] } } } ] }, "Reading": { "type": "object", "required": [ "schema", "kind", "locale", "title", "content_version", "publication", "disclosure", "sections", "evidence", "reading_sha256" ], "properties": { "schema": { "const": "cosmicephemeris-symbolic-reading-v1" }, "kind": { "enum": [ "tarot", "birth", "compatibility", "numerology", "ongoing" ] }, "locale": { "$ref": "#/components/schemas/Locale" }, "title": { "type": "string" }, "content_version": { "type": "string" }, "publication": { "type": "object", "required": [ "practitioner_reviewed", "translation_reviewed", "external_ai_provider" ], "properties": { "practitioner_reviewed": { "const": false }, "translation_reviewed": { "const": false }, "external_ai_provider": { "const": false } } }, "disclosure": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "text", "evidence_ids" ], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string" }, "evidence_ids": { "type": "array", "items": { "type": "string" } } } } }, "evidence": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "value", "source" ] } }, "reading_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } } } } }