{"openapi":"3.0.3","info":{"title":"Feriado.dev API","description":"Brazilian Holidays REST API. Query national, state, and municipal holidays for Brazil, including movable holidays derived from Easter.","version":"1.0.0","contact":{"name":"Feriado.dev","url":"https://feriado.dev"},"license":{"name":"MIT"}},"servers":[{"url":"https://folga-dev-api.rodrigorodrigueses-iatest.workers.dev/api/v1","description":"Production"},{"url":"http://localhost:8787/api/v1","description":"Local development"}],"paths":{"/holidays":{"get":{"summary":"List holidays","description":"Returns a list of holidays filtered by year, month, state, city, and/or type.","operationId":"listHolidays","tags":["Holidays"],"parameters":[{"name":"year","in":"query","required":true,"description":"Year to query (2020-2045)","schema":{"type":"integer","minimum":2020,"maximum":2045,"example":2025}},{"name":"month","in":"query","required":false,"description":"Month to filter (1-12)","schema":{"type":"integer","minimum":1,"maximum":12,"example":12}},{"name":"state","in":"query","required":false,"description":"2-letter state code (UF), e.g. SP, RJ, MG","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"SP"}},{"name":"city","in":"query","required":false,"description":"7-digit IBGE city code. Requires 'state' parameter.","schema":{"type":"string","pattern":"^\\d{7}$","example":"3550308"}},{"name":"type","in":"query","required":false,"description":"Comma-separated list of holiday types: national, state, municipal, optional","schema":{"type":"string","example":"national,optional"}},{"name":"include_bridges","in":"query","required":false,"description":"Include bridge days (emendas de feriado). When a holiday falls on Tuesday, the Monday before is a bridge day; when on Thursday, the Friday after. Requires Pro plan.","schema":{"type":"boolean","default":false,"example":true}}],"responses":{"200":{"description":"List of holidays","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidayListResponse"},"example":{"year":2025,"count":2,"holidays":[{"date":"2025-01-01","name":"Confraternização Universal","name_en":"New Year's Day","type":"national","scope_type":"national","scope_code":"BR","category":"civil","half_day":false},{"date":"2025-04-18","name":"Sexta-feira Santa","name_en":"Good Friday","type":"national","scope_type":"national","scope_code":"BR","category":"religious","half_day":false}]}}}},"400":{"description":"Invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"MISSING_PARAMETER","message":"Parameter 'year' is required","param":"year"}}}}}}}},"/holidays/{date}":{"get":{"summary":"Check if a date is a holiday","description":"Checks whether a specific date is a holiday and returns matching holidays.","operationId":"checkHoliday","tags":["Holidays"],"parameters":[{"name":"date","in":"path","required":true,"description":"Date in YYYY-MM-DD format","schema":{"type":"string","format":"date","example":"2025-12-25"}},{"name":"state","in":"query","required":false,"description":"2-letter state code (UF)","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"SP"}},{"name":"city","in":"query","required":false,"description":"7-digit IBGE city code. Requires 'state' parameter.","schema":{"type":"string","pattern":"^\\d{7}$","example":"3550308"}}],"responses":{"200":{"description":"Holiday check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidayCheckResponse"},"examples":{"is_holiday":{"summary":"Date is a holiday","value":{"date":"2025-12-25","is_holiday":true,"holidays":[{"date":"2025-12-25","name":"Natal","name_en":"Christmas","type":"national","scope_type":"national","scope_code":"BR","category":"religious","half_day":false}]}},"not_holiday":{"summary":"Date is not a holiday","value":{"date":"2025-03-15","is_holiday":false,"holidays":[]}}}}}},"400":{"description":"Invalid date format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"INVALID_PARAMETER","message":"Parameter 'date' must be in YYYY-MM-DD format","param":"date"}}}}}}}},"/states":{"get":{"summary":"List all states","description":"Returns all 26 Brazilian states plus Distrito Federal.","operationId":"listStates","tags":["States"],"responses":{"200":{"description":"List of states","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StateListResponse"},"example":{"count":27,"states":[{"uf":"SP","name":"São Paulo","ibge_code":"35"}]}}}}}}},"/states/{uf}/cities":{"get":{"summary":"List cities for a state","description":"Returns all cities for the given state UF code.","operationId":"listCities","tags":["States"],"parameters":[{"name":"uf","in":"path","required":true,"description":"2-letter state code (UF)","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"SP"}},{"name":"search","in":"query","required":false,"description":"Search filter for city name (minimum 2 characters)","schema":{"type":"string","minLength":2,"example":"Camp"}}],"responses":{"200":{"description":"List of cities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityListResponse"},"example":{"state":"SP","count":2,"cities":[{"ibge_code":"3509502","name":"Campinas","state_uf":"SP"}]}}}},"400":{"description":"Invalid UF format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"State not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"NOT_FOUND","message":"State 'XX' not found"}}}}}}}},"/business-days":{"get":{"summary":"Calculate business days","description":"Calculates the number of business days between two dates, excluding weekends and holidays.","operationId":"calculateBusinessDays","tags":["Business Days"],"parameters":[{"name":"start","in":"query","required":true,"description":"Start date in YYYY-MM-DD format","schema":{"type":"string","format":"date","example":"2026-01-01"}},{"name":"end","in":"query","required":true,"description":"End date in YYYY-MM-DD format","schema":{"type":"string","format":"date","example":"2026-01-31"}},{"name":"state","in":"query","required":false,"description":"2-letter state code (UF) to include state holidays","schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"SP"}},{"name":"city","in":"query","required":false,"description":"7-digit IBGE city code to include municipal holidays. Requires 'state' parameter.","schema":{"type":"string","pattern":"^\\d{7}$","example":"3550308"}},{"name":"include_optional","in":"query","required":false,"description":"Whether to exclude pontos facultativos as business days (default: false)","schema":{"type":"boolean","default":false,"example":false}}],"responses":{"200":{"description":"Business days calculation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessDaysResponse"},"example":{"start":"2026-01-01","end":"2026-01-31","business_days":21,"total_days":31,"weekends":9,"holidays":1,"holidays_on_weekends":0}}}},"400":{"description":"Invalid or missing parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":"MISSING_PARAMETER","message":"Parameter 'start' is required","param":"start"}}}}}}}}},"components":{"schemas":{"Holiday":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Holiday date in YYYY-MM-DD format"},"name":{"type":"string","description":"Holiday name in Portuguese"},"name_en":{"type":"string","nullable":true,"description":"Holiday name in English"},"type":{"type":"string","enum":["national","state","municipal","optional","bridge"],"description":"Holiday type"},"scope_type":{"type":"string","enum":["national","state","municipal"],"description":"Scope of the holiday"},"scope_code":{"type":"string","description":"Scope code (e.g. BR, BR-SP, BR-SP-3550308)"},"category":{"type":"string","nullable":true,"description":"Holiday category (civil, religious, etc.)"},"half_day":{"type":"boolean","description":"Whether this is a half-day holiday"}},"required":["date","name","type","scope_type","scope_code","half_day"]},"HolidayListResponse":{"type":"object","properties":{"year":{"type":"integer"},"count":{"type":"integer"},"holidays":{"type":"array","items":{"$ref":"#/components/schemas/Holiday"}}},"required":["year","count","holidays"]},"HolidayCheckResponse":{"type":"object","properties":{"date":{"type":"string","format":"date"},"is_holiday":{"type":"boolean"},"holidays":{"type":"array","items":{"$ref":"#/components/schemas/Holiday"}}},"required":["date","is_holiday","holidays"]},"State":{"type":"object","properties":{"uf":{"type":"string","description":"2-letter state code"},"name":{"type":"string","description":"State name"},"ibge_code":{"type":"string","description":"IBGE state code"}},"required":["uf","name","ibge_code"]},"StateListResponse":{"type":"object","properties":{"count":{"type":"integer"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}}},"required":["count","states"]},"City":{"type":"object","properties":{"ibge_code":{"type":"string","description":"7-digit IBGE city code"},"name":{"type":"string","description":"City name"},"state_uf":{"type":"string","description":"2-letter state code"}},"required":["ibge_code","name","state_uf"]},"CityListResponse":{"type":"object","properties":{"state":{"type":"string"},"count":{"type":"integer"},"cities":{"type":"array","items":{"$ref":"#/components/schemas/City"}}},"required":["state","count","cities"]},"BusinessDaysResponse":{"type":"object","properties":{"start":{"type":"string","format":"date","description":"Start date"},"end":{"type":"string","format":"date","description":"End date"},"business_days":{"type":"integer","description":"Number of business days in the range"},"total_days":{"type":"integer","description":"Total calendar days in the range (inclusive)"},"weekends":{"type":"integer","description":"Number of weekend days (Saturday + Sunday)"},"holidays":{"type":"integer","description":"Number of holidays falling on weekdays"},"holidays_on_weekends":{"type":"integer","description":"Number of holidays falling on weekends"}},"required":["start","end","business_days","total_days","weekends","holidays","holidays_on_weekends"]},"BridgeDay":{"type":"object","description":"A bridge day (emenda de feriado) created when a holiday falls on Tuesday or Thursday.","properties":{"date":{"type":"string","format":"date","description":"Bridge day date in YYYY-MM-DD format"},"name":{"type":"string","description":"Bridge day name, e.g. 'Emenda - Tiradentes'"},"type":{"type":"string","enum":["bridge"],"description":"Always 'bridge' for bridge days"},"related_holiday":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"The related holiday date"},"name":{"type":"string","description":"The related holiday name"}},"required":["date","name"]}},"required":["date","name","type","related_holiday"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Error code (e.g. MISSING_PARAMETER, INVALID_PARAMETER, NOT_FOUND)"},"message":{"type":"string","description":"Human-readable error message"},"param":{"type":"string","description":"The parameter that caused the error"}},"required":["code","message"]}},"required":["error"]}}}}