{"openapi":"3.1.0","info":{"title":"Festejo (Celebration) API","version":"0.1.0","description":"A fully local Brazilian holidays and festivals guide: fixed national holidays, computed movable holidays (Carnaval, Easter, Corpus Christi) derived from a verified Easter-date algorithm, major popular festas, national-vs-regional coverage, food and tradition guides, and a glossary.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://festejo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/festejo/docs"},"termsOfService":"https://connectorbay.com/festejo/terms"},"servers":[{"url":"https://festejo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/festejo/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/holiday_info":{"post":{"operationId":"holiday_info","summary":"One Brazilian holiday's description, typical traditions, typical foods, and whether its date is fixed","description":"One Brazilian holiday's description, typical traditions, typical foods, and whether its date is fixed\n    or Easter-relative. Covers the fixed national holidays, the Easter-relative movable holidays, and major\n    popular festas (Festa Junina, Réveillon). Use for \"what is Tiradentes Day\", \"tell me about Carnaval\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"A holiday name.","examples":["Natal","Carnaval","Tiradentes","Corpus Christi","Festa Junina"],"minLength":1,"title":"Name","type":"string"}},"required":["name"],"title":"holiday_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/holiday_search":{"post":{"operationId":"holiday_search","summary":"Search Brazilian holidays and festas by keyword across name, description, traditions and foods. Use","description":"Search Brazilian holidays and festas by keyword across name, description, traditions and foods. Use\n    for \"which holidays involve fireworks\", \"what holidays have a food tradition with corn\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"description":"Keyword to search across holiday name, description, traditions and foods.","minLength":1,"title":"Query","type":"string"}},"required":["query"],"title":"holiday_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/holidays_by_month":{"post":{"operationId":"holidays_by_month","summary":"Which FIXED-date Brazilian holidays fall in a given month. Movable Easter-relative holidays (Carnaval,","description":"Which FIXED-date Brazilian holidays fall in a given month. Movable Easter-relative holidays (Carnaval,\n    Good Friday, Páscoa, Corpus Christi) are not included here since their month varies by year — use\n    calendar_year for those. Use for \"what holidays are in September\", \"is there a holiday in November\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"month":{"description":"Calendar month, 1-12.","maximum":12,"minimum":1,"title":"Month","type":"integer"}},"required":["month"],"title":"holidays_by_monthArguments","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/national_vs_regional":{"post":{"operationId":"national_vs_regional","summary":"Distinguishes nationally-observed Brazilian holidays from widely-known but regional/local festas.","description":"Distinguishes nationally-observed Brazilian holidays from widely-known but regional/local festas.\n    type=\"national\" returns the official feriados nacionais (fixed + Easter-relative). type=\"regional\"\n    returns well-known local festas that are not nationally observed (Bumba Meu Boi in the North/Northeast,\n    Círio de Nazaré in Belém, Carnatal in Natal, and others), each with its home region. Use for \"is Bumba\n    Meu Boi a national holiday\", \"what regional festivals does Brazil have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"default":"national","description":"national | regional","title":"Type","type":"string"}},"title":"national_vs_regionalArguments","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/festa_junina_guide":{"post":{"operationId":"festa_junina_guide","summary":"A detailed guide to Festa Junina, Brazil's month-long June harvest-and-saints festival: typical foods","description":"A detailed guide to Festa Junina, Brazil's month-long June harvest-and-saints festival: typical foods\n    (canjica, pamonha, quentão, paçoca, pé-de-moleque), the quadrilha square dance, bonfires, caipira dress,\n    and its timing around the saints' days of Santo Antônio, São João and São Pedro. Use for \"what is Festa\n    Junina\", \"what do people eat at Festa Junina\", \"what's a quadrilha\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"festa_junina_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/carnaval_guide":{"post":{"operationId":"carnaval_guide","summary":"A guide to Brazilian Carnaval: blocos de rua, escolas de samba and the Sambódromo parade competition,","description":"A guide to Brazilian Carnaval: blocos de rua, escolas de samba and the Sambódromo parade competition,\n    and how it varies by region — Rio de Janeiro's samba-school parade, Bahia's trio elétrico street\n    Carnaval, and Recife/Olinda's frevo and maracatu Carnaval in Pernambuco. Use for \"how is Carnaval\n    celebrated in Bahia\", \"what's the difference between Rio and Recife Carnaval\", \"what's a bloco\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"carnaval_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/traditional_food_guide":{"post":{"operationId":"traditional_food_guide","summary":"The typical foods eaten for a given Brazilian holiday. Use for \"what do Brazilians eat at Christmas\",","description":"The typical foods eaten for a given Brazilian holiday. Use for \"what do Brazilians eat at Christmas\",\n    \"what food is served at Réveillon\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"holiday":{"description":"A holiday name.","examples":["Natal","Páscoa","Festa Junina","Réveillon"],"minLength":1,"title":"Holiday","type":"string"}},"required":["holiday"],"title":"traditional_food_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/calendar_year":{"post":{"operationId":"calendar_year","summary":"Brazil's full holiday calendar for a given year: every fixed-date holiday, plus Easter Sunday,","description":"Brazil's full holiday calendar for a given year: every fixed-date holiday, plus Easter Sunday,\n    Carnaval Tuesday, Good Friday and Corpus Christi computed fresh from a verified Easter-date algorithm\n    (the Anonymous Gregorian / Meeus-Jones-Butcher algorithm) — never a hardcoded per-year table. Use for\n    \"when is Carnaval in 2027\", \"what date is Easter in 2030\", \"give me the full 2026 holiday calendar\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"year":{"description":"The calendar year to compute Brazil's holiday calendar for.","maximum":3000,"minimum":1583,"title":"Year","type":"integer"}},"required":["year"],"title":"calendar_yearArguments","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/glossary":{"post":{"operationId":"glossary","summary":"Definitions of Brazilian holiday and festival terms (feriado, ponto facultativo, feriadão, bloco,","description":"Definitions of Brazilian holiday and festival terms (feriado, ponto facultativo, feriadão, bloco,\n    quadrilha, escola de samba, réveillon, arraiá, trio elétrico, frevo) — including the practically useful\n    distinction between an official feriado and a merely-common, non-mandatory ponto facultativo. Use for\n    \"what's a ponto facultativo\", \"what does bloco 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":"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}}}}