{"openapi":"3.1.0","info":{"title":"nextbank.holiday API","version":"1.0.0","description":"Next bank holiday by country and region. Free for people and scripts (rate limited). Clients identified as AI agents pay 0.001 USD per request via x402."},"servers":[{"url":"https://nextbank.holiday"}],"paths":{"/api/v1/regions":{"get":{"summary":"List countries and regions","parameters":[{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","de","es"],"default":"en"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"402":{"description":"Payment required (x402): 0.001 USD per request for AI agents"},"429":{"description":"Rate limited"}}}},"/api/v1/{country}/{region}/next":{"get":{"summary":"Next holiday in a region","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["gb","ie","fr","de","es"]}},{"name":"region","in":"path","required":true,"schema":{"type":"string","enum":["england-and-wales","scotland","northern-ireland","ireland","metropole","alsace-moselle","baden-wuerttemberg","bayern","berlin","brandenburg","bremen","hamburg","hessen","mecklenburg-vorpommern","niedersachsen","nordrhein-westfalen","rheinland-pfalz","saarland","sachsen","sachsen-anhalt","schleswig-holstein","thueringen","andalucia","aragon","asturias","baleares","canarias","cantabria","castilla-la-mancha","castilla-y-leon","cataluna","comunidad-valenciana","extremadura","galicia","la-rioja","madrid","murcia","navarra","pais-vasco","ceuta","melilla"]}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","de","es"],"default":"en"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"region":{"type":"string","example":"gb/scotland"},"today":{"type":"string","format":"date"},"timezone":{"type":"string"},"today_holiday":{"type":"object","properties":{"date":{"type":"string","format":"date"},"name":{"type":"string"},"slug":{"type":"string"},"substitute":{"type":"boolean"}}},"next":{"type":["object","null"],"properties":{"date":{"type":"string","format":"date"},"name":{"type":"string"},"slug":{"type":"string"},"substitute":{"type":"boolean"},"days_until":{"type":"integer"}}}}}}}},"402":{"description":"Payment required (x402): 0.001 USD per request for AI agents"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited"}}}},"/api/v1/{country}/{region}/holidays":{"get":{"summary":"All holidays in a year","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["gb","ie","fr","de","es"]}},{"name":"region","in":"path","required":true,"schema":{"type":"string","enum":["england-and-wales","scotland","northern-ireland","ireland","metropole","alsace-moselle","baden-wuerttemberg","bayern","berlin","brandenburg","bremen","hamburg","hessen","mecklenburg-vorpommern","niedersachsen","nordrhein-westfalen","rheinland-pfalz","saarland","sachsen","sachsen-anhalt","schleswig-holstein","thueringen","andalucia","aragon","asturias","baleares","canarias","cantabria","castilla-la-mancha","castilla-y-leon","cataluna","comunidad-valenciana","extremadura","galicia","la-rioja","madrid","murcia","navarra","pais-vasco","ceuta","melilla"]}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","de","es"],"default":"en"}},{"name":"year","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"holidays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"name":{"type":"string"},"slug":{"type":"string"},"substitute":{"type":"boolean"}}}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402): 0.001 USD per request for AI agents"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited"}}}},"/api/v1/next":{"get":{"summary":"Next holiday addressed by ISO codes","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string","example":"GB"}},{"name":"region","in":"query","schema":{"type":"string","example":"SCT"}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","de","es"],"default":"en"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"region":{"type":"string","example":"gb/scotland"},"today":{"type":"string","format":"date"},"timezone":{"type":"string"},"today_holiday":{"type":"object","properties":{"date":{"type":"string","format":"date"},"name":{"type":"string"},"slug":{"type":"string"},"substitute":{"type":"boolean"}}},"next":{"type":["object","null"],"properties":{"date":{"type":"string","format":"date"},"name":{"type":"string"},"slug":{"type":"string"},"substitute":{"type":"boolean"},"days_until":{"type":"integer"}}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402): 0.001 USD per request for AI agents"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited"}}}},"/{country}/{region}.ics":{"get":{"summary":"iCalendar feed","parameters":[{"name":"country","in":"path","required":true,"schema":{"type":"string","enum":["gb","ie","fr","de","es"]}},{"name":"region","in":"path","required":true,"schema":{"type":"string","enum":["england-and-wales","scotland","northern-ireland","ireland","metropole","alsace-moselle","baden-wuerttemberg","bayern","berlin","brandenburg","bremen","hamburg","hessen","mecklenburg-vorpommern","niedersachsen","nordrhein-westfalen","rheinland-pfalz","saarland","sachsen","sachsen-anhalt","schleswig-holstein","thueringen","andalucia","aragon","asturias","baleares","canarias","cantabria","castilla-la-mancha","castilla-y-leon","cataluna","comunidad-valenciana","extremadura","galicia","la-rioja","madrid","murcia","navarra","pais-vasco","ceuta","melilla"]}},{"name":"lang","in":"query","schema":{"type":"string","enum":["en","fr","de","es"],"default":"en"}}],"responses":{"200":{"description":"text/calendar"},"402":{"description":"Payment required (x402): 0.001 USD per request for AI agents"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited"}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}