{
  "openapi": "3.1.0",
  "info": {
    "title": "SoulOS Kundli API",
    "version": "2.0.0",
    "summary": "Vedic astrology (Jyotish) REST API: kundli, 24 divisional charts, Jaimini, 3 dasha systems, matching, panchang.",
    "description": "SoulOS Engine, Lahiri ayanamsa, whole-sign houses, BPHS rules. Every plan gets every endpoint; plans differ by volume. Free: 100 calls/day. Accuracy is checked against published charts (Gandhi, Nehru, Indira Gandhi, Vivekananda, Tendulkar): planets and Lagna within ~1 arc-minute, identical D1/D9 signs. Docs: https://kundli.soulmapbysahil.in/docs/",
    "contact": {
      "name": "SoulOS API support",
      "email": "care@kohli.tel",
      "url": "https://kundli.soulmapbysahil.in/docs/#support"
    }
  },
  "servers": [
    {
      "url": "https://kundli.soulmapbysahil.in"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Birth Chart"
    },
    {
      "name": "Charts & Systems"
    },
    {
      "name": "Matching"
    },
    {
      "name": "Time & Numbers"
    }
  ],
  "paths": {
    "/v1/chart": {
      "post": {
        "operationId": "getBirthChart",
        "summary": "Birth chart (kundli)",
        "description": "Complete Vedic birth chart from date, time and place: Lagna with degree, 9 grahas (sign, degree, nakshatra, pada, retrograde, combust), 12 whole-sign houses, Avkahada Chakra, 5-level Vimshottari Dasha with the running chain, 40 Parashari yogas, optional North Indian chart SVG and natal interpretation (en/hi/hinglish).",
        "tags": [
          "Birth Chart"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dob": {
                    "type": "string",
                    "description": "Date of birth, YYYY-MM-DD",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "example": "1987-07-08"
                  },
                  "tob": {
                    "type": "string",
                    "description": "Local time of birth, HH:MM or HH:MM:SS (24-hour)",
                    "example": "19:25"
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude of birth place, decimal degrees (north positive)",
                    "example": 30.7333
                  },
                  "lon": {
                    "type": "number",
                    "description": "Longitude of birth place, decimal degrees (east positive)",
                    "example": 76.7794
                  },
                  "tz": {
                    "type": "number",
                    "description": "UTC offset in hours at the birth date and place. Default 5.5 (IST)",
                    "default": 5.5,
                    "example": 5.5
                  },
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "name": {
                    "type": "string",
                    "description": "Echoed back; used in interpretation text"
                  },
                  "dasha_depth": {
                    "type": "integer",
                    "description": "Vimshottari levels 1–5 (default 5)",
                    "minimum": 1,
                    "maximum": 5
                  },
                  "chart": {
                    "type": "boolean",
                    "description": "Include North Indian chart SVG in data.chart_svg"
                  },
                  "chart_theme": {
                    "description": "Chart look: cosmic (default), classic or minimal; or a list such as [\"cosmic\",\"minimal\"] to get data.chart_svgs",
                    "oneOf": [
                      {
                        "type": "string",
                        "enum": [
                          "cosmic",
                          "classic",
                          "minimal"
                        ]
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "cosmic",
                            "classic",
                            "minimal"
                          ]
                        }
                      }
                    ]
                  },
                  "chart_labels": {
                    "type": "string",
                    "description": "Sign labels: numbers (default) or names",
                    "enum": [
                      "numbers",
                      "names"
                    ]
                  },
                  "chart_title": {
                    "type": "boolean",
                    "description": "Show the chart name above it (default true)"
                  },
                  "include": {
                    "type": "array",
                    "description": "Optional expansions, e.g. [\"insights\"]",
                    "items": {
                      "type": "string",
                      "enum": [
                        "insights"
                      ]
                    }
                  },
                  "lang": {
                    "type": "string",
                    "description": "Language of insights: en, hi, hg"
                  }
                },
                "required": [
                  "dob",
                  "tob",
                  "lat",
                  "lon"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "dob": "1987-07-08",
                "tob": "19:25",
                "lat": 30.7333,
                "lon": 76.7794,
                "tz": 5.5,
                "chart": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/divisional": {
      "post": {
        "operationId": "getDivisionalCharts",
        "summary": "Divisional (varga) charts: 24 charts",
        "description": "Any of 24 divisional charts: the 16 Shodashavarga (D1–D60) plus D5, D6, D8, D11, D81, D108 (2 variants), D144 and D150. Each chart returns the Lagna and every planet with sign, degree inside the varga, house, and a birth-time window: minutes the birth time can be off before that chart's Lagna changes sign (uses the real Ascendant speed). One call can return all 24 charts.",
        "tags": [
          "Charts & Systems"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dob": {
                    "type": "string",
                    "description": "Date of birth, YYYY-MM-DD",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "example": "1987-07-08"
                  },
                  "tob": {
                    "type": "string",
                    "description": "Local time of birth, HH:MM or HH:MM:SS (24-hour)",
                    "example": "19:25"
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude of birth place, decimal degrees (north positive)",
                    "example": 30.7333
                  },
                  "lon": {
                    "type": "number",
                    "description": "Longitude of birth place, decimal degrees (east positive)",
                    "example": 76.7794
                  },
                  "tz": {
                    "type": "number",
                    "description": "UTC offset in hours at the birth date and place. Default 5.5 (IST)",
                    "default": 5.5,
                    "example": 5.5
                  },
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "chart": {
                    "description": "\"D9\", [\"D6\",\"D9\"], or a group: all, shodashavarga, extended, higher",
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ]
                  },
                  "variants": {
                    "type": "object",
                    "description": "Calculation variant per chart, e.g. {\"D108\": \"d12_then_d9\"}"
                  },
                  "svg": {
                    "type": "boolean",
                    "description": "Add a North Indian chart SVG per chart"
                  },
                  "chart_theme": {
                    "description": "Chart look: cosmic (default), classic or minimal; or a list for several (chart_svgs)",
                    "oneOf": [
                      {
                        "type": "string",
                        "enum": [
                          "cosmic",
                          "classic",
                          "minimal"
                        ]
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string",
                          "enum": [
                            "cosmic",
                            "classic",
                            "minimal"
                          ]
                        }
                      }
                    ]
                  },
                  "chart_labels": {
                    "type": "string",
                    "description": "Sign labels: numbers (default) or names",
                    "enum": [
                      "numbers",
                      "names"
                    ]
                  },
                  "chart_title": {
                    "type": "boolean",
                    "description": "Show the chart name above each chart (default true)"
                  }
                },
                "required": [
                  "dob",
                  "tob",
                  "lat",
                  "lon"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "dob": "1987-07-08",
                "tob": "19:25",
                "lat": 30.7333,
                "lon": 76.7794,
                "tz": 5.5,
                "chart": "all"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/jaimini": {
      "post": {
        "operationId": "getJaimini",
        "summary": "Jaimini system",
        "description": "Jaimini astrology in one call: Chara Karakas (8 or 7 scheme), Karakamsha with Ishta Devata sign, Arudha Padas A1–A12 (Arudha Lagna, Upapada), Rashi Drishti (sign aspects), Argala on all 12 houses, and Chara Dasha (K.N. Rao) with antardashas and the running period.",
        "tags": [
          "Charts & Systems"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dob": {
                    "type": "string",
                    "description": "Date of birth, YYYY-MM-DD",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "example": "1987-07-08"
                  },
                  "tob": {
                    "type": "string",
                    "description": "Local time of birth, HH:MM or HH:MM:SS (24-hour)",
                    "example": "19:25"
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude of birth place, decimal degrees (north positive)",
                    "example": 30.7333
                  },
                  "lon": {
                    "type": "number",
                    "description": "Longitude of birth place, decimal degrees (east positive)",
                    "example": 76.7794
                  },
                  "tz": {
                    "type": "number",
                    "description": "UTC offset in hours at the birth date and place. Default 5.5 (IST)",
                    "default": 5.5,
                    "example": 5.5
                  },
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "include": {
                    "type": "array",
                    "description": "Sections: karakas, karakamsha, arudha, drishti, argala, chara_dasha (default all)",
                    "items": {
                      "type": "string"
                    }
                  },
                  "karaka_scheme": {
                    "type": "integer",
                    "description": "8 (default, includes Rahu) or 7",
                    "enum": [
                      7,
                      8
                    ]
                  },
                  "exaltation_adjustment": {
                    "type": "boolean",
                    "description": "Chara Dasha ±1 year for exalted/debilitated lord (default true)"
                  },
                  "date": {
                    "type": "string",
                    "description": "Date for the running Chara Dasha, YYYY-MM-DD (default today IST)"
                  }
                },
                "required": [
                  "dob",
                  "tob",
                  "lat",
                  "lon"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "dob": "1987-07-08",
                "tob": "19:25",
                "lat": 30.7333,
                "lon": 76.7794,
                "tz": 5.5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/dasha": {
      "post": {
        "operationId": "getDashas",
        "summary": "Dasha systems: Vimshottari, Yogini, Chara",
        "description": "Three dasha systems in one call: Vimshottari (1–5 levels: Mahadasha to Prana, birth period laid out from its true start), Yogini (36-year cycle, with antardashas) and Jaimini Chara Dasha. Each returns balance at birth, the periods running on a chosen date, and the timeline. Set timeline=false for a tiny 'what is running now' response.",
        "tags": [
          "Charts & Systems"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dob": {
                    "type": "string",
                    "description": "Date of birth, YYYY-MM-DD",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "example": "1987-07-08"
                  },
                  "tob": {
                    "type": "string",
                    "description": "Local time of birth, HH:MM or HH:MM:SS (24-hour)",
                    "example": "19:25"
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude of birth place, decimal degrees (north positive)",
                    "example": 30.7333
                  },
                  "lon": {
                    "type": "number",
                    "description": "Longitude of birth place, decimal degrees (east positive)",
                    "example": 76.7794
                  },
                  "tz": {
                    "type": "number",
                    "description": "UTC offset in hours at the birth date and place. Default 5.5 (IST)",
                    "default": 5.5,
                    "example": 5.5
                  },
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "systems": {
                    "type": "array",
                    "description": "vimshottari, yogini, chara (default all)",
                    "items": {
                      "type": "string",
                      "enum": [
                        "vimshottari",
                        "yogini",
                        "chara"
                      ]
                    }
                  },
                  "depth": {
                    "type": "integer",
                    "description": "Vimshottari levels 1–5 (default 3)",
                    "minimum": 1,
                    "maximum": 5
                  },
                  "date": {
                    "type": "string",
                    "description": "Date for running periods, YYYY-MM-DD (default today IST)"
                  },
                  "timeline": {
                    "type": "boolean",
                    "description": "false = balance + current only (default true)"
                  }
                },
                "required": [
                  "dob",
                  "tob",
                  "lat",
                  "lon"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "dob": "1987-07-08",
                "tob": "19:25",
                "lat": 30.7333,
                "lon": 76.7794,
                "tz": 5.5,
                "systems": [
                  "vimshottari",
                  "yogini"
                ],
                "timeline": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/timezone": {
      "post": {
        "operationId": "getTimezone",
        "summary": "Correct UTC offset for a birth",
        "description": "The UTC offset actually in force at a place on a local date and time: summer time, half-hour zones, India war time 1941–45 (+6:30) and local mean time before standard time. Pass the result as tz to every other endpoint. Always send country; without it the zone is chosen by distance and can be wrong near borders.",
        "tags": [
          "Charts & Systems"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude of birth place, decimal degrees (north positive)",
                    "example": 30.7333
                  },
                  "lon": {
                    "type": "number",
                    "description": "Longitude of birth place, decimal degrees (east positive)",
                    "example": 76.7794
                  },
                  "country": {
                    "type": "string",
                    "description": "2-letter ISO country code, e.g. IN, US (strongly recommended)"
                  },
                  "region": {
                    "type": "string",
                    "description": "State or province for the USA, Canada and Australia: ISO 3166-2 code (US-TX) or name (Texas)"
                  },
                  "date": {
                    "type": "string",
                    "description": "Local date YYYY-MM-DD"
                  },
                  "time": {
                    "type": "string",
                    "description": "Local time HH:MM (default 12:00)"
                  }
                },
                "required": [
                  "lat",
                  "lon",
                  "date"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "lat": 28.6139,
                "lon": 77.209,
                "country": "IN",
                "date": "1943-06-15",
                "time": "10:00"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/dosha": {
      "post": {
        "operationId": "getDoshas",
        "summary": "Doshas: Mangal, Shrapit, Pitra, Sadhe Sati",
        "description": "The four classical doshas with BPHS references: Mangal (Kuja) Dosha with cancellation checks, Shrapit, Pitra, and Sadhe Sati for any date. Kaal Sarp is deliberately not included (no classical source).",
        "tags": [
          "Charts & Systems"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "dob": {
                    "type": "string",
                    "description": "Date of birth, YYYY-MM-DD",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "example": "1987-07-08"
                  },
                  "tob": {
                    "type": "string",
                    "description": "Local time of birth, HH:MM or HH:MM:SS (24-hour)",
                    "example": "19:25"
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude of birth place, decimal degrees (north positive)",
                    "example": 30.7333
                  },
                  "lon": {
                    "type": "number",
                    "description": "Longitude of birth place, decimal degrees (east positive)",
                    "example": 76.7794
                  },
                  "tz": {
                    "type": "number",
                    "description": "UTC offset in hours at the birth date and place. Default 5.5 (IST)",
                    "default": 5.5,
                    "example": 5.5
                  },
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "gochar_date": {
                    "type": "string",
                    "description": "Date for Sadhe Sati (Saturn transit), YYYY-MM-DD (default today IST)"
                  }
                },
                "required": [
                  "dob",
                  "tob",
                  "lat",
                  "lon"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "dob": "1987-07-08",
                "tob": "19:25",
                "lat": 30.7333,
                "lon": 76.7794,
                "tz": 5.5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/compatibility": {
      "post": {
        "operationId": "getCompatibility",
        "summary": "Kundli Milan: Ashtakoot 36 guna",
        "description": "Ashtakoot (36-guna) matching with all 8 kootas, dosha notes and a verdict. Mode A: pass boy_nakshatra, boy_rashi, girl_nakshatra, girl_rashi. Mode B: pass full boy{} and girl{} birth details.",
        "tags": [
          "Matching"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "boy": {
                    "type": "object",
                    "description": "Birth details: dob, tob, lat, lon, tz"
                  },
                  "girl": {
                    "type": "object",
                    "description": "Birth details: dob, tob, lat, lon, tz"
                  },
                  "boy_nakshatra": {
                    "type": "string"
                  },
                  "boy_rashi": {
                    "type": "string"
                  },
                  "girl_nakshatra": {
                    "type": "string"
                  },
                  "girl_rashi": {
                    "type": "string"
                  }
                },
                "required": []
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "boy": {
                  "dob": "1990-04-12",
                  "tob": "08:30",
                  "lat": 28.61,
                  "lon": 77.21,
                  "tz": 5.5
                },
                "girl": {
                  "dob": "1992-09-03",
                  "tob": "17:45",
                  "lat": 19.08,
                  "lon": 72.88,
                  "tz": 5.5
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/synastry": {
      "post": {
        "operationId": "getSynastry",
        "summary": "Synastry: Graha-Sthiti overlay",
        "description": "Parashari planetary overlay between two charts: each person's planets placed in the other's houses, with themes, interpretations and a dasha narrative.",
        "tags": [
          "Matching"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "p1": {
                    "type": "object",
                    "description": "Person 1: dob, tob, lat, lon, tz, name"
                  },
                  "p2": {
                    "type": "object",
                    "description": "Person 2: same fields"
                  },
                  "interpret": {
                    "type": "boolean",
                    "description": "Include interpretations (default true)"
                  }
                },
                "required": [
                  "p1",
                  "p2"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "p1": {
                  "dob": "1990-04-12",
                  "tob": "08:30",
                  "lat": 28.61,
                  "lon": 77.21,
                  "tz": 5.5,
                  "name": "A"
                },
                "p2": {
                  "dob": "1992-09-03",
                  "tob": "17:45",
                  "lat": 19.08,
                  "lon": 72.88,
                  "tz": 5.5,
                  "name": "B"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/panchang": {
      "post": {
        "operationId": "getPanchang",
        "summary": "Panchang for any date and place",
        "description": "Vara, Tithi (with paksha), Nakshatra (with pada), Yoga, Karana, Sun/Moon longitudes, progress through each element, and festivals for the date.",
        "tags": [
          "Time & Numbers"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "date": {
                    "type": "string",
                    "description": "YYYY-MM-DD"
                  },
                  "time": {
                    "type": "string",
                    "description": "HH:MM local (default 00:00)"
                  },
                  "lat": {
                    "type": "number",
                    "description": "Latitude of birth place, decimal degrees (north positive)",
                    "example": 30.7333
                  },
                  "lon": {
                    "type": "number",
                    "description": "Longitude of birth place, decimal degrees (east positive)",
                    "example": 76.7794
                  },
                  "tz": {
                    "type": "number",
                    "description": "UTC offset in hours at the birth date and place. Default 5.5 (IST)",
                    "default": 5.5,
                    "example": 5.5
                  }
                },
                "required": [
                  "date",
                  "lat",
                  "lon"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "date": "2026-11-20",
                "time": "06:30",
                "lat": 28.61,
                "lon": 77.21,
                "tz": 5.5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    },
    "/v1/ankashastra": {
      "post": {
        "operationId": "getAnkashastra",
        "summary": "Ankashastra: Vedic numerology",
        "description": "Moolank, Bhagyank, Naam Ank (Vedic phonetic), Universal and Personal Day, and Naisargik Maitri compatibility.",
        "tags": [
          "Time & Numbers"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "api_key": {
                    "type": "string",
                    "description": "Your API key (or send it as Authorization: Bearer <key>)"
                  },
                  "dob": {
                    "type": "string",
                    "description": "Date of birth, YYYY-MM-DD",
                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                    "example": "1987-07-08"
                  },
                  "name": {
                    "type": "string",
                    "description": "Full name: enables Naam Ank"
                  },
                  "date": {
                    "type": "string",
                    "description": "YYYY-MM-DD for Universal/Personal Day (default today IST)"
                  },
                  "moon_rashi": {
                    "type": "integer",
                    "description": "Natal Moon sign 1–12",
                    "minimum": 1,
                    "maximum": 12
                  }
                },
                "required": [
                  "dob"
                ]
              },
              "example": {
                "api_key": "YOUR_API_KEY",
                "dob": "1987-07-08",
                "name": "Asha Verma"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success. Envelope: {status: \"success\", data: {...}, meta: {...}}",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/EngineError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer YOUR_API_KEY. You can also send api_key in the JSON body. Free key: https://kundli.soulmapbysahil.in/dev/register"
      }
    },
    "schemas": {
      "Success": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "success"
            ]
          },
          "data": {
            "type": "object"
          },
          "meta": {
            "type": "object"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "INVALID_JSON, MISSING_FIELD, INVALID_INPUT, INVALID_CHART, INVALID_VARIANT",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "AUTH_FAILED: key missing or not recognised",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "AUTH_FAILED: key inactive or plan expired",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "RATE_LIMITED: daily or per-minute limit reached. See Retry-After and X-RateLimit-* headers",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "EngineError": {
        "description": "ENGINE_ERROR: calculation failed; retry once",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}