{"openapi":"3.1.0","info":{"title":"Falak (Astronomy) API","version":"0.1.0","description":"A fully local reference on the historical Islamic Golden Age astronomy tradition: Arabic-origin star names, historically significant astronomers, the astrolabe, traditional moon-phase observation, and constellation etymology.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://falak.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/falak/docs"},"termsOfService":"https://connectorbay.com/falak/terms"},"servers":[{"url":"https://falak.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/falak/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/star_name_info":{"post":{"operationId":"star_name_info","summary":"A star's Arabic-origin name etymology, literal meaning, and which constellation it is in — covers 28","description":"A star's Arabic-origin name etymology, literal meaning, and which constellation it is in — covers 28\n    bright stars still known today by their Arabic-derived names. Use for \"what does Aldebaran mean\", \"why is\n    it called Betelgeuse\", \"what constellation is Altair in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A star's common name.","examples":["Aldebaran","Betelgeuse","Altair","Vega","Rigel","Deneb","Algol"],"title":"Name","type":"string"}},"required":["name"],"title":"star_name_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/star_search":{"post":{"operationId":"star_search","summary":"Search all covered stars by partial name, alias, constellation, or a word from their etymology or","description":"Search all covered stars by partial name, alias, constellation, or a word from their etymology or\n    meaning. Use for \"which stars are in Orion\", \"stars whose name means eagle\", \"Arabic star names in Ursa\n    Major\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Partial name, alias, constellation, or a word from a star's meaning or etymology.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"star_searchArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/astronomer_info":{"post":{"operationId":"astronomer_info","summary":"One historically significant Islamic Golden Age astronomer's dates, birthplace and key contributions,","description":"One historically significant Islamic Golden Age astronomer's dates, birthplace and key contributions,\n    verified against public history-of-science reference sources. Use for \"who was al-Battani\", \"what did\n    al-Biruni discover\", \"when did Ibn al-Shatir live\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A historical Islamic Golden Age astronomer's name.","examples":["al-Battani","al-Sufi","Ibn al-Shatir","al-Biruni","al-Tusi","al-Zarqali","Ulugh Beg"],"title":"Name","type":"string"}},"required":["name"],"title":"astronomer_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/astronomers_list":{"post":{"operationId":"astronomers_list","summary":"Lists all seven covered Islamic Golden Age astronomers with a one-line summary each. Use for \"which","description":"Lists all seven covered Islamic Golden Age astronomers with a one-line summary each. Use for \"which\n    astronomers do you cover\", \"list Islamic Golden Age astronomers\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"astronomers_listArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/astrolabe_guide":{"post":{"operationId":"astrolabe_guide","summary":"What an astrolabe is, its historical purposes (astronomy, timekeeping, navigation and surveying, and","description":"What an astrolabe is, its historical purposes (astronomy, timekeeping, navigation and surveying, and\n    prayer-time/qibla calculation), and its basic construction (mater, climate plates, rete, alidade, throne).\n    Use for \"what is an astrolabe\", \"how does an astrolabe work\", \"what are the parts of an astrolabe\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"astrolabe_guideArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/constellation_info":{"post":{"operationId":"constellation_info","summary":"A constellation's Arabic-origin name and etymology where the historical Arabic astronomical tradition","description":"A constellation's Arabic-origin name and etymology where the historical Arabic astronomical tradition\n    named or renamed it, and which Arabic-named stars it contains. Use for \"what's the Arabic name for\n    Orion\", \"why is Ursa Major called al-Dubb al-Akbar\", \"is there an Arabic name for the Big Bear\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A constellation's name.","examples":["Orion","Ursa Major","Cygnus","Pegasus","Leo","Scorpius","Aquarius"],"title":"Name","type":"string"}},"required":["name"],"title":"constellation_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/moon_phase_observation_guide":{"post":{"operationId":"moon_phase_observation_guide","summary":"Traditional naked-eye moon-phase observation methods historically used for lunar calendar-keeping —","description":"Traditional naked-eye moon-phase observation methods historically used for lunar calendar-keeping —\n    the synodic month, the phase sequence, and how the young crescent (hilal) was traditionally sighted.\n    Astronomical and historical framing, not a religious ruling. Use for \"how did people track moon phases\n    before telescopes\", \"what is the hilal\", \"how long is a lunar month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"moon_phase_observation_guideArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/historical_context_info":{"post":{"operationId":"historical_context_info","summary":"A general historical note on the Islamic Golden Age's astronomical scholarship — the translation","description":"A general historical note on the Islamic Golden Age's astronomical scholarship — the translation\n    movement, the House of Wisdom, major observatories (Baghdad, Maragheh, Samarkand) — and its documented\n    transmission to European astronomy, including Copernicus's use of al-Battani's work. Use for \"how did\n    Islamic astronomy influence Europe\", \"what was the House of Wisdom\", \"did Copernicus use Islamic\n    astronomy\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"historical_context_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/astronomy_glossary":{"post":{"operationId":"astronomy_glossary","summary":"Definitions of core historical-astronomy terms (astrolabe, zij, azimuth, nadir, zenith, alidade,","description":"Definitions of core historical-astronomy terms (astrolabe, zij, azimuth, nadir, zenith, alidade,\n    muwaqqit, hilal, rubu/sine quadrant, qibla, ecliptic, elongation), noting Arabic etymology where it\n    applies. Use for \"what does azimuth mean\", \"what is a muwaqqit\", \"what does zij mean\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"term":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"A specific term to look up; omit to list all.","title":"Term"}},"title":"astronomy_glossaryArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}