{"openapi":"3.1.0","info":{"title":"Refnusa API","version":"0.1.0","description":"Indonesian reference data; every record names its source_instrument and effective_date."},"servers":[{"url":"https://refnusa.dev"}],"paths":{"/v1/datasets":{"get":{"summary":"Coverage of every dataset: status, row count, source instrument, effective date.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/holidays":{"get":{"summary":"Public holidays (libur nasional) and joint leave days (cuti bersama) for one year, from that year's SKB 3 Menteri decree.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","description":"Calendar year, for example 2026","minimum":2000,"maximum":2100}}]}},"/v1/holidays/{date}":{"get":{"summary":"Whether one date is a public holiday or cuti bersama, with the decree it was checked against.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"date","in":"path","required":true,"schema":{"type":"string","description":"Date in YYYY-MM-DD form","format":"date"}}]}},"/v1/wages/ump":{"get":{"summary":"Provincial minimum wage (UMP) for one year, all provinces or one province, with the governor decree behind each figure.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","description":"Calendar year, for example 2026","minimum":2000,"maximum":2100}},{"name":"province_code","in":"query","required":false,"schema":{"type":"string","description":"Kemendagri province code, optional","pattern":"^\\d{2}$"}}]}},"/v1/wages/umk":{"get":{"summary":"Regency or city minimum wage (UMK) for one year, starter set of the largest regencies only.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"year","in":"query","required":true,"schema":{"type":"integer","description":"Calendar year, for example 2026","minimum":2000,"maximum":2100}},{"name":"regency_code","in":"query","required":true,"schema":{"type":"string","description":"Kemendagri kabupaten/kota code","pattern":"^\\d{2}\\.\\d{2}$"}}]}},"/v1/wilayah":{"get":{"summary":"Administrative regions: the 38 provinces, the children of one parent code, or one region by code.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"level","in":"query","required":false,"schema":{"type":"string","description":"Level to list; anything below provinsi needs parent_code","enum":["provinsi","kabupaten","kecamatan","kelurahan"]}},{"name":"parent_code","in":"query","required":false,"schema":{"type":"string","description":"List the children of this code","pattern":"^\\d{2}(\\.\\d{2}){0,2}(\\.\\d{4})?$"}},{"name":"code","in":"query","required":false,"schema":{"type":"string","description":"Return this one region","pattern":"^\\d{2}(\\.\\d{2}){0,2}(\\.\\d{4})?$"}}]}},"/v1/wilayah/{code}":{"get":{"summary":"One administrative region by code.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string","description":"Kemendagri wilayah code","pattern":"^\\d{2}(\\.\\d{2}){0,2}(\\.\\d{4})?$"}}]}},"/v1/postal-codes/reverse":{"get":{"summary":"Regions that carry one postal code.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string","description":"Postal code","pattern":"^\\d{5}$"}}]}},"/v1/postal-codes/{wilayah_code}":{"get":{"summary":"Postal codes of one kelurahan or desa by its wilayah code.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"wilayah_code","in":"path","required":true,"schema":{"type":"string","description":"Kemendagri wilayah code","pattern":"^\\d{2}(\\.\\d{2}){0,2}(\\.\\d{4})?$"}}]}},"/v1/tax/pph21-ter":{"get":{"summary":"PPh 21 effective average rate (TER) bracket for a monthly gross income and TER category A, B or C, per PP 58/2023.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","description":"TER category A, B or C","enum":["A","B","C"]}},{"name":"income_idr","in":"query","required":true,"schema":{"type":"integer","description":"Monthly gross income in rupiah","minimum":0}}]}},"/v1/tax/ptkp":{"get":{"summary":"Annual non-taxable income (PTKP) for a taxpayer status such as TK/0 or K/1.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"status","in":"query","required":true,"schema":{"type":"string","description":"PTKP status code","pattern":"^(TK|K|K\\/I)\\/[0-3]$"}}]}},"/v1/prayer-times":{"get":{"summary":"Prayer times for one kabupaten/kota and date, computed by a documented hisab method; not an official Kemenag feed.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"city_code","in":"query","required":true,"schema":{"type":"string","description":"Kemendagri kabupaten/kota code; a kecamatan or kelurahan code falls back to its parent","pattern":"^\\d{2}(\\.\\d{2}){0,2}(\\.\\d{4})?$"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","description":"Date in YYYY-MM-DD form","format":"date"}}]}},"/v1/validate/nik":{"post":{"summary":"Checks the structure of a 16-digit NIK and looks up its region digits in the wilayah table. Send the NIK in the JSON body; it is never logged.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["nik"],"properties":{"nik":{"type":"string","description":"The 16-digit NIK","maxLength":32}}}}}}}},"/v1/validate/plate":{"get":{"summary":"Checks the format of an Indonesian vehicle plate and names the region of its prefix when the prefix table is loaded.","responses":{"200":{"description":"OK"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"plate","in":"query","required":true,"schema":{"type":"string","description":"Plate such as B 1234 XYZ","maxLength":16}}]}}},"components":{"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}