{"openapi":"3.1.0","info":{"title":"Persian Calendar API","version":"1.0.0","description":"Anonymous, read-only civil-date utilities powered by the same jalaali-js engine as the website. Dates are not astronomical event times. Cultural/weekend markers are not an official public-holiday schedule. Supply an explicit IANA timezone for location-dependent today queries."},"servers":[{"url":"https://persiancalendar.online"}],"security":[],"externalDocs":{"url":"https://persiancalendar.online/developers"},"paths":{"/api/convert":{"get":{"operationId":"convert_date","summary":"Convert a Gregorian or Persian civil date","description":"Input year limits: Gregorian 1800–2200; Persian 1280–1600. These are input-specific policies, not symmetric output limits. No timezone is applied. Valid response fields retain the original API contract.","parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string","enum":["gregorian","persian"],"description":"Calendar of the input date.","default":"gregorian"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","minLength":10,"maxLength":10,"description":"ASCII YYYY-MM-DD in the selected input calendar."}}],"responses":{"200":{"description":"Validated input and its equivalent date in the other calendar.","content":{"application/json":{"schema":{"type":"object","properties":{"input":{"type":"object","properties":{"year":{"type":"integer","minimum":1},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31},"calendar":{"type":"string","enum":["gregorian","persian"]},"monthName":{"type":"string"}},"required":["calendar","year","month","day"]},"result":{"type":"object","properties":{"year":{"type":"integer","minimum":1},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31},"calendar":{"type":"string","enum":["gregorian","persian"]},"monthName":{"type":"string"},"monthNameFa":{"type":"string"},"season":{"type":"string","enum":["spring","summer","autumn","winter"]}},"required":["calendar","year","month","day"]}},"required":["input","result"]}}}},"400":{"description":"Missing, malformed, impossible or unsupported input.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/today":{"get":{"operationId":"get_today","summary":"Today in an explicit timezone","description":"Omitting timeZone preserves the original server-timezone behavior. Agents should supply it explicitly. Responses are not cached. isHoliday retains its original meaning: a stored cultural date or Friday, not an official holiday decision.","parameters":[{"name":"timeZone","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100,"description":"IANA timezone, for example Asia/Tehran, Europe/London or UTC."},"example":"Asia/Tehran"}],"responses":{"200":{"description":"Current Gregorian and Persian components, calculation timestamp and resolved timezone.","content":{"application/json":{"schema":{"type":"object","properties":{"persian":{"type":"object","properties":{"year":{"type":"integer","minimum":1},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31},"monthName":{"type":"string"},"monthNameFa":{"type":"string"},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6},"dayOfWeekName":{"type":"string"},"season":{"type":"string"},"isHoliday":{"type":"boolean"}},"required":["year","month","day","monthName","monthNameFa","dayOfWeek","dayOfWeekName","season","isHoliday"]},"gregorian":{"type":"object","properties":{"year":{"type":"integer","minimum":1},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31}},"required":["year","month","day"]},"timestamp":{"type":"string","format":"date-time"},"timeZone":{"type":"string"}},"required":["persian","gregorian","timestamp","timeZone"]}}}},"400":{"description":"Missing, malformed, impossible or unsupported input.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/month":{"get":{"operationId":"get_persian_month","summary":"Persian month length and Gregorian boundaries","parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","minimum":1280,"maximum":1600}},{"name":"month","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":12}}],"responses":{"200":{"description":"Exact civil-date boundaries; firstWeekdayIndex is Saturday = 0 through Friday = 6.","content":{"application/json":{"schema":{"type":"object","properties":{"persian":{"type":"object","properties":{"year":{"type":"integer","minimum":1},"month":{"type":"integer","minimum":1,"maximum":12},"monthName":{"type":"string"},"monthNameFa":{"type":"string"},"days":{"type":"integer","minimum":29,"maximum":31},"isLeapYear":{"type":"boolean"},"season":{"type":"string"}},"required":["year","month","monthName","monthNameFa","days","isLeapYear","season"]},"gregorian":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}},"required":["start","end"]},"weekStartsOn":{"type":"string","const":"saturday"},"firstWeekdayIndex":{"type":"integer","minimum":0,"maximum":6},"source":{"type":"string","format":"uri"}},"required":["persian","gregorian","weekStartsOn","firstWeekdayIndex","source"]}}}},"400":{"description":"Missing, malformed, impossible or unsupported input.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}