{"openapi":"3.1.0","info":{"title":"MABIMS API","description":"## MABIMS API\n\nMABIMS.dev adalah API unofficial, gratis, dan open-source untuk kalender Hijriah Indonesia. Ambil tanggal Hijriah hari ini, konversi tanggal, kalender bulanan dan tahunan, data visibilitas hilal, serta hari besar Islam berdasarkan data resmi MABIMS dari Kementerian Agama RI.\n\nHalaman ini adalah **playground** untuk mencoba endpoint secara interaktif. Untuk panduan awal dan dokumentasi lengkap, kunjungi [mabims.dev/quickstart](https://mabims.dev/quickstart).\n\n## Perilaku lintas-endpoint\n\n- **Tanpa autentikasi** — semua endpoint publik; pembatasan laju per IP.\n- **HEAD tersedia di setiap endpoint** dengan header yang sama, tanpa body.\n- **Revalidasi ETag** — setiap respons 200 membawa `ETag`; kirim `If-None-Match` dengannya (perbandingan lemah, atau `*`) dan origin menjawab **304 Not Modified** dengan `Cache-Control` dan `ETag` yang sama.\n- **Amplop error seragam** — setiap error (validasi, 404, 429, …) berbentuk `{\"error\": {\"code\": \"...\", \"message\": \"...\"}}`; 429 menyertakan header `Retry-After` dalam detik.\n- **Nilai tidak peka huruf besar/kecil** untuk nilai bertuliskan (`calendar=hijri`, `retro=true`); flag boolean menerima `1`/`0`.\n- **CORS terbuka** — semua origin diizinkan. Self-hoster bisa membatasi lewat `ALLOWED_ORIGINS`; origin terlarang mendapat 403 `forbidden_origin`.","version":"1.10.0","contact":{"name":"PIXO Studio","email":"halo@pixostudio.id"},"license":{"name":"MIT","url":"https://github.com/PijarAdiluhung/mabims-api/blob/main/LICENSE"}},"servers":[{"url":"https://api.mabims.dev","description":"Live API"}],"paths":{"/api/v1/today":{"get":{"tags":["Today"],"summary":"Tanggal Hijriah hari ini","description":"Mengembalikan tanggal Hijriah untuk hari ini di zona waktu yang diminta.","operationId":"today_api_v1_today_head","parameters":[{"name":"tz","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Zona waktu IANA (mis. `Asia/Jakarta`) atau UTC offset (mis. `+08:00`). Default `Asia/Jakarta` (UTC+7). Hanya dipakai oleh `/today`.","title":"Tz"},"description":"Zona waktu IANA (mis. `Asia/Jakarta`) atau UTC offset (mis. `+08:00`). Default `Asia/Jakarta` (UTC+7). Hanya dipakai oleh `/today`.","example":"Asia/Jakarta"},{"$ref":"#/components/parameters/NextParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TodayResponse"}}}},"400":{"description":"Invalid timezone or next parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"invalid_timezone","message":"Unknown timezone: Foo/Bar"}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=60, s-maxage until midnight in the requested timezone.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/today/{target_date}":{"get":{"tags":["Today"],"summary":"Tanggal Hijriah untuk tanggal Masehi tertentu","description":"Sama seperti /today tapi untuk tanggal Masehi tertentu. Immutable, aman di-cache CDN selamanya. Tidak menerima `tz`.","operationId":"today_on_api_v1_today__target_date__head","parameters":[{"name":"target_date","in":"path","required":true,"schema":{"type":"string","title":"Target Date"},"example":"2025-01-03"},{"$ref":"#/components/parameters/RetroParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertResponse"}}}},"400":{"description":"Invalid date or retro parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"invalid_date","message":"'1999-13-45' is not a valid ISO date (YYYY-MM-DD)."}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/convert":{"get":{"tags":["Convert"],"summary":"Konversi satu tanggal","description":"Mengkonversi satu tanggal Masehi ke Hijriah saat `calendar=gregorian`, dan Hijriah ke Masehi saat `calendar=hijri`. Tidak bergantung pada zona waktu.","operationId":"convert_api_v1_convert_head","parameters":[{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tanggal ISO (`YYYY-MM-DD`), misalnya 2025-01-03 atau 1446-07-03","title":"Date"},"description":"Tanggal ISO (`YYYY-MM-DD`), misalnya 2025-01-03 atau 1446-07-03","example":"2025-01-03"},{"name":"calendar","in":"query","required":false,"schema":{"type":"string","description":"Kalender dari tanggal input: `gregorian` atau `hijri`","default":"gregorian","title":"Calendar"},"description":"Kalender dari tanggal input: `gregorian` atau `hijri`","example":"gregorian"},{"$ref":"#/components/parameters/RetroParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/range":{"get":{"tags":["Range"],"summary":"Konversi massal rentang tanggal","description":"Mengkonversi setiap hari dalam rentang tanggal (maksimal 45 hari). Immutable, aman di-cache selama satu hari penuh.","operationId":"range__api_v1_range_head","parameters":[{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tanggal mulai ISO (`YYYY-MM-DD`), dengan `start` ≤ `end` dan rentang maks 45 hari","title":"Start"},"description":"Tanggal mulai ISO (`YYYY-MM-DD`), dengan `start` ≤ `end` dan rentang maks 45 hari","example":"2025-01-01"},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tanggal akhir ISO (`YYYY-MM-DD`), dengan `start` ≤ `end` dan rentang maks 45 hari","title":"End"},"description":"Tanggal akhir ISO (`YYYY-MM-DD`), dengan `start` ≤ `end` dan rentang maks 45 hari","example":"2025-01-31"},{"name":"calendar","in":"query","required":false,"schema":{"type":"string","description":"Kalender dari tanggal input: `gregorian` atau `hijri`","default":"gregorian","title":"Calendar"},"description":"Kalender dari tanggal input: `gregorian` atau `hijri`","example":"gregorian"},{"name":"step","in":"query","required":false,"schema":{"type":"string","description":"Hanya `day` yang didukung","default":"day","title":"Step"},"description":"Hanya `day` yang didukung","example":"day"},{"$ref":"#/components/parameters/RetroParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RangeResponse"}}}},"400":{"description":"Invalid range, step, calendar, or date out of coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"invalid_range","message":"'start' must be on or before 'end'."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/month":{"get":{"tags":["Month"],"summary":"Semua hari dalam satu bulan","description":"Mengembalikan semua hari dalam satu bulan. Untuk `calendar=hijri`, setiap item berisi tanggal Masehi yang menjadi acuan hari Hijriah tersebut.","operationId":"month_api_v1_month_head","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tahun Hijriah atau Masehi (mis. 1447)","title":"Year"},"description":"Tahun Hijriah atau Masehi (mis. 1447)","example":"1447"},{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulan 1-12","title":"Month"},"description":"Bulan 1-12","example":"3"},{"name":"calendar","in":"query","required":false,"schema":{"type":"string","description":"Kalender dari tanggal input: `gregorian` atau `hijri`","default":"hijri","title":"Calendar"},"description":"Kalender dari tanggal input: `gregorian` atau `hijri`","example":"hijri"},{"$ref":"#/components/parameters/RetroParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthResponse"}}}},"400":{"description":"Invalid month, year, calendar, or date out of coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"invalid_month","message":"'month' must be between 1 and 12."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/months":{"get":{"tags":["Months"],"summary":"Daftar nama bulan Hijriah","description":"Mengembalikan 12 nama bulan Hijriah beserta nomornya. Statis, dapat di-cache — gunakan ini untuk mengisi dropdown UI.","operationId":"months_api_v1_months_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthsResponse"}}}},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/year":{"get":{"tags":["Year"],"summary":"Semua hari dalam satu tahun","description":"Mengembalikan semua hari dalam 1 tahun (total 12 bulan baik Hijriah maupun Masehi).","operationId":"year_api_v1_year_head","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tahun Hijriah atau Masehi (mis. 1447)","title":"Year"},"description":"Tahun Hijriah atau Masehi (mis. 1447)","example":"1447"},{"name":"calendar","in":"query","required":false,"schema":{"type":"string","description":"Kalender dari tanggal input: `gregorian` atau `hijri`","default":"hijri","title":"Calendar"},"description":"Kalender dari tanggal input: `gregorian` atau `hijri`","example":"hijri"},{"$ref":"#/components/parameters/RetroParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/YearResponse"}}}},"400":{"description":"Invalid year, calendar, or date out of coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"invalid_year","message":"'year' is out of supported bounds."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/events":{"get":{"tags":["Events"],"summary":"Hari besar Islam dalam satu tahun","description":"Mengembalikan tanggal hari penting Islam untuk satu tahun. Event dasar (1 Muharram, Maulid Nabi, Awal Ramadan, Idul Fitri, Idul Adha) selalu tersedia; tambahkan `include=extra` untuk peringatan tingkat dua (Isra Mi'raj, Nuzulul Quran, Arafah, Tasu'a, Asyura, Tasyrik), `include=ayyamul_bidh` untuk puasa hari putih (13-15 setiap bulan Hijriah), slug individual untuk memilih satu per satu, atau `all` untuk semuanya.","operationId":"events_api_v1_events_head","parameters":[{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tahun kalender sesuai `calendar` (Hijriah: 1446, Masehi: 2025)","title":"Year"},"description":"Tahun kalender sesuai `calendar` (Hijriah: 1446, Masehi: 2025)","example":"1447"},{"name":"calendar","in":"query","required":false,"schema":{"type":"string","description":"Kalender dari tanggal input: `gregorian` atau `hijri`","default":"hijri","title":"Calendar"},"description":"Kalender dari tanggal input: `gregorian` atau `hijri`","example":"hijri"},{"name":"include","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tambahan opsional, dipisah koma: `extra` (peringatan tingkat dua), `ayyamul_bidh`, slug individual (isra_miraj, nuzulul_quran, arafah, tasua, asyura, tasyrik), atau `all`. Event dasar selalu disertakan; nilai tidak dikenal ditolak dengan 400 `invalid_include`.","title":"Include"},"description":"Tambahan opsional, dipisah koma: `extra` (peringatan tingkat dua), `ayyamul_bidh`, slug individual (isra_miraj, nuzulul_quran, arafah, tasua, asyura, tasyrik), atau `all`. Event dasar selalu disertakan; nilai tidak dikenal ditolak dengan 400 `invalid_include`."},{"$ref":"#/components/parameters/RetroParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}},"400":{"description":"Invalid year or calendar parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"invalid_year","message":"'year' is out of supported bounds."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/hilal/info":{"get":{"tags":["Hilal"],"summary":"Data visibilitas hilal","description":"Data visibilitas hilal untuk malam penentu awal bulan Hijriah. Kriteria Neo MABIMS dievaluasi di 25 titik pesisir saat matahari terbenam.","operationId":"hilal_info_api_v1_hilal_info_head","parameters":[{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulan Hijriah target (1-12)","title":"Month"},"description":"Bulan Hijriah target (1-12)","example":"3"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tahun Hijriah target (mis. 1447)","title":"Year"},"description":"Tahun Hijriah target (mis. 1447)","example":"1447"},{"$ref":"#/components/parameters/RetroParam"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HilalInfoResponse"}}}},"400":{"description":"Month out of coverage or date out of supported range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"out_of_coverage","message":"No calendar pair exists for 2022-01-01; check /api/v1/meta for coverage."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: public, max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}},"required":["month","year"]}},"/api/v1/hilal/history":{"get":{"tags":["Hilal"],"summary":"Riwayat hilal (indeks terhitung)","description":"Ringkasan hilal per bulan untuk rentang Hijriah YYYY-MM.","operationId":"hilal_history_api_v1_hilal_history_head","parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulan awal rentang Hijriah `YYYY-MM` (mis. 1445-08)","title":"From"},"description":"Bulan awal rentang Hijriah `YYYY-MM` (mis. 1445-08)","example":"1446-01"},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulan akhir rentang Hijriah `YYYY-MM` (mis. 1475-12)","title":"To"},"description":"Bulan akhir rentang Hijriah `YYYY-MM` (mis. 1475-12)","example":"1446-12"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HilalHistoryResponse"}}}},"400":{"description":"Invalid date range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"invalid_range","message":"'start' must be on or before 'end'."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: public, max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}}}},"/api/v1/hilal/viz":{"get":{"tags":["Hilal"],"summary":"Grafik langit hilal PNG","description":"Mengembalikan PNG 720x1280 grafik langit senja untuk melihat hilal. Tambahkan `bare=true` untuk kartu tanpa panel, `download=true` untuk menerimanya sebagai attachment.","operationId":"hilal_viz_api_v1_hilal_viz_head","parameters":[{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulan Hijriah target (1-12)","title":"Month"},"description":"Bulan Hijriah target (1-12)","example":"3"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tahun Hijriah target (mis. 1447)","title":"Year"},"description":"Tahun Hijriah target (mis. 1447)","example":"1447"},{"$ref":"#/components/parameters/RetroParam"},{"$ref":"#/components/parameters/BareParam"},{"$ref":"#/components/parameters/DownloadParam"}],"responses":{"200":{"description":"Hilal card PNG (720×1280; bare variant 1440×1520)","content":{"image/png":{}}},"400":{"description":"Year out of image range or date out of coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"out_of_coverage","message":"No calendar pair exists for 2022-01-01; check /api/v1/meta for coverage."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: public, max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}},"required":["month","year"]}},"/api/v1/hilal/map":{"get":{"tags":["Hilal"],"summary":"Peta visibilitas hilal PNG","description":"Mengembalikan PNG 720x1280 peta visibilitas Nusantara. Tambahkan `bare=true` untuk kartu tanpa panel, `download=true` untuk menerimanya sebagai attachment.","operationId":"hilal_map_api_v1_hilal_map_head","parameters":[{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Bulan Hijriah target (1-12)","title":"Month"},"description":"Bulan Hijriah target (1-12)","example":"3"},{"name":"year","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Tahun Hijriah target (mis. 1447)","title":"Year"},"description":"Tahun Hijriah target (mis. 1447)","example":"1447"},{"$ref":"#/components/parameters/RetroParam"},{"$ref":"#/components/parameters/BareParam"},{"$ref":"#/components/parameters/DownloadParam"}],"responses":{"200":{"description":"Hilal card PNG (720×1280; bare variant 1440×1520)","content":{"image/png":{}}},"400":{"description":"Year out of image range or date out of coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"out_of_coverage","message":"No calendar pair exists for 2022-01-01; check /api/v1/meta for coverage."}}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/ServiceUnavailable"},"304":{"description":"Not Modified — the If-None-Match header matched the current ETag. Cache-Control: public, max-age=86400.","headers":{"ETag":{"description":"Entity tag of the 200 body; compare weakly with If-None-Match.","schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string"}}}}},"required":["month","year"]}},"/api/v1/meta":{"get":{"tags":["Meta"],"summary":"Metadata API","description":"Info dataset yang machine-readable: versi data, cakupan tabel, status tier komputasi, rentang render hilal, dan koreksi Sidang Isbat.","operationId":"meta_api_v1_meta_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaResponse"}}}}}}},"/healthz":{"get":{"tags":["Health"],"summary":"Probe liveness","description":"Probe liveness untuk monitor uptime. Tidak pernah di-cache.","operationId":"healthz_healthz_head","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}}},"components":{"schemas":{"ConversionInput":{"properties":{"date":{"type":"string","title":"Date"},"calendar":{"type":"string","title":"Calendar"},"tz":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tz"}},"type":"object","required":["date","calendar"],"title":"ConversionInput"},"ConversionOutput":{"properties":{"date":{"type":"string","title":"Date"},"calendar":{"type":"string","title":"Calendar"},"day":{"type":"integer","title":"Day"},"month":{"type":"integer","title":"Month"},"month_name":{"type":"string","title":"Month Name"},"year":{"type":"integer","title":"Year"},"weekday":{"type":"string","title":"Weekday","description":"Nama hari untuk tanggal kalender tersebut (Ahad, Senin, ..., Sabtu)"}},"type":"object","required":["date","calendar","day","month","month_name","year","weekday"],"title":"ConversionOutput"},"ConvertResponse":{"properties":{"input":{"$ref":"#/components/schemas/ConversionInput"},"output":{"$ref":"#/components/schemas/ConversionOutput"},"source":{"type":"string","enum":["mabims","mabims-computed","mabims-retro"],"title":"Source","description":"Asal data: `mabims` = data publik Kemenag, `mabims-computed` = dihitung dengan kriteria Neo MABIMS, `mabims-retro` = kriteria Neo MABIMS diproyeksikan ke belakang di bawah tabel kurasi"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Tidak kosong saat berlaku bulan di batas ambang, fallback komputasi, atau proyeksi retro"}},"type":"object","required":["input","output","source"],"title":"ConvertResponse"},"Coverage":{"properties":{"first":{"type":"string","title":"First"},"last":{"type":"string","title":"Last"}},"type":"object","required":["first","last"],"title":"Coverage"},"DecidingSite":{"properties":{"name":{"type":"string","title":"Name"},"lat":{"type":"number","title":"Lat"},"lon":{"type":"number","title":"Lon"},"elev_m":{"type":"number","title":"Elev M"},"tz":{"type":"string","title":"Tz","description":"Zona waktu IANA yang dipakai untuk waktu yang ditampilkan di titik pengamatan"}},"type":"object","required":["name","lat","lon","elev_m","tz"],"title":"DecidingSite","description":"Titik pengamatan pesisir yang menentukan putusan visibilitas."},"EventDateRange":{"properties":{"hijri_start":{"type":"string","title":"Hijri Start"},"hijri_end":{"type":"string","title":"Hijri End"},"gregorian_start":{"type":"string","title":"Gregorian Start"},"gregorian_end":{"type":"string","title":"Gregorian End"}},"type":"object","required":["hijri_start","hijri_end","gregorian_start","gregorian_end"],"title":"EventDateRange"},"EventItem":{"properties":{"event":{"type":"string","title":"Event"},"name":{"type":"string","title":"Name"},"hijri":{"type":"string","title":"Hijri"},"gregorian":{"type":"string","title":"Gregorian"},"source":{"type":"string","enum":["mabims","mabims-computed","mabims-retro"],"title":"Source"},"date_range":{"anyOf":[{"$ref":"#/components/schemas/EventDateRange"},{"type":"null"}],"description":"Rentang event multi-hari (day..day_end dalam Hijriah). null untuk event satu hari."}},"type":"object","required":["event","name","hijri","gregorian","source"],"title":"EventItem"},"EventsInput":{"properties":{"year":{"type":"integer","title":"Year"},"calendar":{"type":"string","title":"Calendar"},"include":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Include","description":"gema dari query `include`; null saat tidak diisi (event dasar saja)"}},"type":"object","required":["year","calendar"],"title":"EventsInput"},"EventsResponse":{"properties":{"input":{"$ref":"#/components/schemas/EventsInput"},"count":{"type":"integer","title":"Count"},"events":{"items":{"$ref":"#/components/schemas/EventItem"},"type":"array","title":"Events"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["input","count","events"],"title":"EventsResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","title":"Status"},"version":{"type":"string","title":"Version"},"build_hash":{"type":"string","title":"Build Hash"}},"type":"object","required":["status","version","build_hash"],"title":"HealthResponse"},"HilalEvening":{"properties":{"hijri_date":{"type":"string","title":"Hijri Date"},"hijri_day":{"type":"integer","title":"Hijri Day"},"gregorian_date":{"type":"string","title":"Gregorian Date"},"sunset":{"type":"string","title":"Sunset"},"moonset":{"type":"string","title":"Moonset"},"moon_alt_deg":{"type":"number","title":"Moon Alt Deg","description":"Ketinggian Bulan tampak toposentris (sudah dikoreksi refraksi) saat matahari terbenam di titik penentu"},"moon_az_deg":{"type":"number","title":"Moon Az Deg","description":"Azimut Bulan saat matahari terbenam di titik penentu, derajat dari utara searah jarum jam"},"sun_alt_deg":{"type":"number","title":"Sun Alt Deg","description":"Ketinggian Matahari saat matahari terbenam di titik penentu"},"elongation_deg":{"type":"number","title":"Elongation Deg","description":"Elongasi Bulan-Matahari geosentris saat matahari terbenam lokal di titik penentu"},"illumination_pct":{"type":"number","title":"Illumination Pct"},"age_hours":{"type":"number","title":"Age Hours"},"deciding_site":{"$ref":"#/components/schemas/DecidingSite","description":"Titik pengamatan pesisir yang menjadi acuan semua nilai, titik penentu atau yang paling mendekati kriteria"},"sites_checked":{"type":"integer","title":"Sites Checked","description":"Jumlah titik pengamatan pesisir yang dievaluasi","default":0},"alt_ok":{"type":"boolean","title":"Alt Ok","description":"Ketinggian Bulan ≥ 3,0 derajat saat matahari terbenam di titik penentu"},"elong_ok":{"type":"boolean","title":"Elong Ok","description":"Elongasi ≥ 6,4 derajat saat matahari terbenam di titik penentu"},"visible":{"type":"boolean","title":"Visible","description":"Bernilai true jika kriteria terpenuhi di setidaknya satu titik pesisir di Indonesia, bukan klaim pengamatan sesungguhnya"}},"type":"object","required":["hijri_date","hijri_day","gregorian_date","sunset","moonset","moon_alt_deg","moon_az_deg","sun_alt_deg","elongation_deg","illumination_pct","age_hours","deciding_site","alt_ok","elong_ok","visible"],"title":"HilalEvening"},"HilalHistoryInput":{"properties":{"from":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From","description":"Bulan Hijriah awal `YYYY-MM` (inklusif)"},"to":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To","description":"Bulan Hijriah akhir `YYYY-MM` (inklusif)"}},"type":"object","title":"HilalHistoryInput"},"HilalHistoryItem":{"properties":{"month":{"$ref":"#/components/schemas/HilalMonth"},"previous_month":{"$ref":"#/components/schemas/HilalPrevMonth"},"evening":{"$ref":"#/components/schemas/HilalEvening"},"source":{"type":"string","enum":["mabims","mabims-computed","mabims-retro"],"title":"Source","description":"Asal data: `mabims` = data publik Kemenag, `mabims-computed` = dihitung dengan kriteria Neo MABIMS, `mabims-retro` = kriteria Neo MABIMS diproyeksikan ke belakang di bawah tabel kurasi"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Tidak kosong saat berlaku bulan di batas ambang, fallback komputasi, atau proyeksi retro"}},"type":"object","required":["month","previous_month","evening","source"],"title":"HilalHistoryItem"},"HilalHistoryResponse":{"properties":{"input":{"$ref":"#/components/schemas/HilalHistoryInput"},"count":{"type":"integer","title":"Count"},"range":{"anyOf":[{"$ref":"#/components/schemas/Coverage"},{"type":"null"}],"description":"Rentang Hijriah `YYYY-MM` yang dicakup indeks terhitung"},"months":{"items":{"$ref":"#/components/schemas/HilalHistoryItem"},"type":"array","title":"Months"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["input","count","months"],"title":"HilalHistoryResponse"},"HilalInfoResponse":{"properties":{"input":{"$ref":"#/components/schemas/HilalInput"},"month":{"$ref":"#/components/schemas/HilalMonth"},"previous_month":{"$ref":"#/components/schemas/HilalPrevMonth"},"evening":{"$ref":"#/components/schemas/HilalEvening"},"source":{"type":"string","enum":["mabims","mabims-computed","mabims-retro"],"title":"Source","description":"Asal data: `mabims` = data publik Kemenag, `mabims-computed` = dihitung dengan kriteria Neo MABIMS, `mabims-retro` = kriteria Neo MABIMS diproyeksikan ke belakang di bawah tabel kurasi"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Tidak kosong saat berlaku bulan di batas ambang, fallback komputasi, atau proyeksi retro"}},"type":"object","required":["input","month","previous_month","evening","source"],"title":"HilalInfoResponse"},"HilalInput":{"properties":{"month":{"type":"integer","title":"Month"},"year":{"type":"integer","title":"Year"}},"type":"object","required":["month","year"],"title":"HilalInput"},"HilalMonth":{"properties":{"name":{"type":"string","title":"Name"},"number":{"type":"integer","title":"Number"},"year":{"type":"integer","title":"Year"},"start":{"type":"string","title":"Start"}},"type":"object","required":["name","number","year","start"],"title":"HilalMonth"},"HilalPrevMonth":{"properties":{"name":{"type":"string","title":"Name"},"number":{"type":"integer","title":"Number"},"year":{"type":"integer","title":"Year"},"length":{"type":"integer","title":"Length"}},"type":"object","required":["name","number","year","length"],"title":"HilalPrevMonth"},"MetaResponse":{"properties":{"version":{"type":"string","title":"Version"},"data_version":{"type":"string","title":"Data Version"},"coverage":{"$ref":"#/components/schemas/Coverage"},"computed_active":{"type":"boolean","title":"Computed Active","default":false},"computed_months":{"items":{"type":"string"},"type":"array","title":"Computed Months"},"method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Method"},"docs_url":{"type":"string","title":"Docs Url"},"hilal_image_range":{"anyOf":[{"items":{"type":"integer"},"type":"array"},{"type":"null"}],"title":"Hilal Image Range","description":"Rentang tahun Hijriah `[min, max]` yang kartu /hilal/viz dan /hilal/map-nya sudah dibuat lebih dulu. Ini kap render, bukan kap data: lihat `coverage.forward_ceil` untuk batas konversi tanggal."},"divergences":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Divergences","description":"Riwayat koreksi Sidang Isbat: setiap entri berisi `hijri_month` (bulan terkoreksi) dan `delta_days` (geseran dalam hari). Kosong bila kalender terbit dan hasil Sidang Isbat sepenuhnya sepakat."},"table_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Version","description":"Token versi riwayat koreksi. Berubah setiap kali koreksi Sidang Isbat diterapkan."}},"type":"object","required":["version","data_version","coverage","docs_url"],"title":"MetaResponse"},"MonthInput":{"properties":{"year":{"type":"integer","title":"Year"},"month":{"type":"integer","title":"Month"},"calendar":{"type":"string","title":"Calendar"}},"type":"object","required":["year","month","calendar"],"title":"MonthInput"},"MonthItem":{"properties":{"number":{"type":"integer","title":"Number"},"name":{"type":"string","title":"Name"}},"type":"object","required":["number","name"],"title":"MonthItem"},"MonthResponse":{"properties":{"input":{"$ref":"#/components/schemas/MonthInput"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/RangeItem"},"type":"array","title":"Items"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["input","count","items"],"title":"MonthResponse"},"MonthsResponse":{"properties":{"calendar":{"type":"string","title":"Calendar"},"months":{"items":{"$ref":"#/components/schemas/MonthItem"},"type":"array","title":"Months"}},"type":"object","required":["calendar","months"],"title":"MonthsResponse"},"NextDate":{"properties":{"date":{"type":"string","title":"Date"},"calendar":{"type":"string","title":"Calendar"},"day":{"type":"integer","title":"Day"},"month":{"type":"integer","title":"Month"},"month_name":{"type":"string","title":"Month Name"},"year":{"type":"integer","title":"Year"},"weekday":{"type":"string","title":"Weekday","description":"Nama hari untuk tanggal kalender tersebut (Ahad, Senin, ..., Sabtu)"},"source":{"type":"string","enum":["mabims","mabims-computed","mabims-retro"],"title":"Source","description":"Asal data: `mabims` = data publik Kemenag, `mabims-computed` = dihitung dengan kriteria Neo MABIMS, `mabims-retro` = kriteria Neo MABIMS diproyeksikan ke belakang di bawah tabel kurasi"}},"type":"object","required":["date","calendar","day","month","month_name","year","weekday","source"],"title":"NextDate"},"RangeInput":{"properties":{"start":{"type":"string","title":"Start"},"end":{"type":"string","title":"End"},"calendar":{"type":"string","title":"Calendar"}},"type":"object","required":["start","end","calendar"],"title":"RangeInput"},"RangeItem":{"properties":{"gregorian":{"type":"string","title":"Gregorian"},"hijri":{"type":"string","title":"Hijri"},"weekday":{"type":"string","title":"Weekday","description":"Nama hari untuk tanggal kalender tersebut (Ahad, Senin, ..., Sabtu)"},"source":{"type":"string","enum":["mabims","mabims-computed","mabims-retro"],"title":"Source"}},"type":"object","required":["gregorian","hijri","weekday","source"],"title":"RangeItem"},"RangeResponse":{"properties":{"input":{"$ref":"#/components/schemas/RangeInput"},"count":{"type":"integer","title":"Count"},"items":{"items":{"$ref":"#/components/schemas/RangeItem"},"type":"array","title":"Items"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["input","count","items"],"title":"RangeResponse"},"TableResponse":{"properties":{"version":{"type":"string","title":"Version"},"gregorian_to_hijri":{"additionalProperties":{"type":"string"},"type":"object","title":"Gregorian To Hijri"},"hijri_to_gregorian":{"additionalProperties":{"type":"string"},"type":"object","title":"Hijri To Gregorian"}},"type":"object","required":["version","gregorian_to_hijri","hijri_to_gregorian"],"title":"TableResponse"},"TodayResponse":{"properties":{"input":{"$ref":"#/components/schemas/ConversionInput"},"output":{"$ref":"#/components/schemas/ConversionOutput"},"source":{"type":"string","enum":["mabims","mabims-computed","mabims-retro"],"title":"Source","description":"Asal data: `mabims` = data publik Kemenag, `mabims-computed` = dihitung dengan kriteria Neo MABIMS, `mabims-retro` = kriteria Neo MABIMS diproyeksikan ke belakang di bawah tabel kurasi"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings","description":"Tidak kosong saat berlaku bulan di batas ambang, fallback komputasi, atau proyeksi retro"},"next":{"anyOf":[{"$ref":"#/components/schemas/NextDate"},{"type":"null"}],"description":"Tanggal Hijriah yang berlaku setelah magrib malam ini. Hanya ada saat `next=true`."}},"type":"object","required":["input","output","source"],"title":"TodayResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"YearInput":{"properties":{"year":{"type":"integer","title":"Year"},"calendar":{"type":"string","title":"Calendar"}},"type":"object","required":["year","calendar"],"title":"YearInput"},"YearResponse":{"properties":{"input":{"$ref":"#/components/schemas/YearInput"},"count":{"type":"integer","title":"Count"},"months":{"additionalProperties":{"items":{"$ref":"#/components/schemas/RangeItem"},"type":"array"},"type":"object","title":"Months"},"warnings":{"items":{"type":"string"},"type":"array","title":"Warnings"}},"type":"object","required":["input","count","months"],"title":"YearResponse"},"ErrorBody":{"title":"ErrorBody","type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","examples":["invalid_date","rate_limit_exceeded"]},"message":{"type":"string","description":"Human-readable explanation of what went wrong."}}},"ErrorResponse":{"title":"ErrorResponse","type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}}}},"parameters":{"RetroParam":{"name":"retro","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Set `true` untuk membuka tanggal retro komputasi di bawah tabel kurasi (dari 1945-01-01 sampai 2022-12-31), ditandai `mabims-retro`. Boolean: `true`/`false` (tidak peka huruf besar/kecil), juga menerima `1`/`0`; nilai lain ditolak dengan 400 `invalid_retro`."},"NextParam":{"name":"next","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Jika di-set `true`, maka API akan mengembalikan juga objek `next` dengan `source` sendiri. Fungsinya untuk menunjukkan tanggal Hijriah setelah magrib malam ini. Kenapa? Karena hari Hijriah dimulai saat magrib, bukan tengah malam. API tidak menghitung waktu matahari terbenam, jadi tentukan momen magrib di sisi klien Anda. Boolean: `true`/`false` (tidak peka huruf besar/kecil), juga menerima `1`/`0`; nilai lain ditolak dengan 400 `invalid_next`."},"BareParam":{"name":"bare","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Hanya untuk `viz` dan `map`: menghilangkan panel kriteria dan mengembalikan kartu resolusi tinggi 1440×1520 (header + grafik + logo) untuk dipakai sebagai gambar hero di web. Boolean: `true`/`false` (tidak peka huruf besar/kecil), juga menerima `1`/`0`; nilai lain ditolak dengan 400 `invalid_bare`."},"DownloadParam":{"name":"download","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Hanya untuk `viz` dan `map`: mengirim `Content-Disposition: attachment` sehingga browser mengunduh PNG alih-alih membukanya. Berguna karena atribut `download` HTML diabaikan untuk URL lintas-origin. Boolean: `true`/`false` (tidak peka huruf besar/kecil), juga menerima `1`/`0`; nilai lain ditolak dengan 400 `invalid_download`."}},"responses":{"NotFound":{"description":"Date not found or path not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"date_not_found","message":"No calendar pair exists for 2026-07-31 (hijri). See /api/v1/meta for coverage."}}}}},"RateLimited":{"description":"Rate Limit Exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"rate_limit_exceeded","message":"Rate limit exceeded (240 per 1 minute). Wait 60s before retrying."}}}}},"BadRequest":{"description":"Bad Request — validation error or missing parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"missing_parameter","message":"You must provide a 'date' query parameter."}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"render_failed","message":"Could not render chart: RenderError"}}}}},"ServiceUnavailable":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"},"example":{"error":{"code":"computation_unavailable","message":"Could not compute hilal data: EphemerisError"}}}}}}},"tags":[{"name":"Today","description":"Tanggal Hijriah hari ini"},{"name":"Convert","description":"Konversi satu tanggal (Masehi/Hijriah)"},{"name":"Range","description":"Konversi massal rentang tanggal (maksimal 45 hari)"},{"name":"Month","description":"Semua hari dalam satu bulan"},{"name":"Months","description":"Nama bulan Hijriah"},{"name":"Year","description":"Semua hari dalam satu tahun"},{"name":"Events","description":"Hari besar Islam: Ramadan, Idul Fitri, Idul Adha, 1 Muharram, Maulid Nabi"},{"name":"Hilal","description":"Data visibilitas hilal dan grafik langit"},{"name":"Meta","description":"Cakupan data, status komputasi, dan versi tabel"},{"name":"Health","description":"Probe liveness"}],"externalDocs":{"description":"Full docs, demo, FAQ and API reference","url":"https://mabims.dev"}}