{"openapi":"3.0.0","info":{"title":"Super Calendar API","version":"2.0.0","description":"Dynamic Calendar Infrastructure"},"servers":[{"url":"/api"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Application health status","description":"Validates the local landing shell, landing locale JSON files,\nfeature registry, and Swagger path coverage.\n\nThis endpoint is intentionally lightweight and does not call\nexternal providers by default.\n","responses":{"200":{"description":"Health checks passed.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"checkedAt":{"type":"string","format":"date-time"},"checkedAtMinute":{"type":"string","example":"2026-05-11 18:30"},"groups":{"type":"object","additionalProperties":true},"summary":{"type":"object","properties":{"total":{"type":"integer"},"ok":{"type":"integer"},"failed":{"type":"integer"}}}},"required":["status","checkedAt","checkedAtMinute","groups","summary"]}}}},"503":{"description":"One or more health checks failed."}}}},"/status.json":{"get":{"tags":["System"],"summary":"Public status snapshot","description":"Returns the current public status snapshot used by `/status`.\n\nThis endpoint is intentionally snapshot-based. It does not perform external\nprovider calls or deep checks at request time.\n","responses":{"200":{"description":"Status snapshot.","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string","example":"super-calendar.status.v1"},"overall":{"type":"string","enum":["operational","degraded","outage"]},"updatedAt":{"type":"string","format":"date-time"},"source":{"type":"string"},"services":{"type":"array","items":{"type":"object","additionalProperties":true}},"history":{"type":"object","additionalProperties":true},"servedAt":{"type":"string","format":"date-time"}},"required":["schema","overall","updatedAt","services","history"]}}}}}}},"/weather":{"get":{"tags":["Weather"],"summary":"Current weather and forecast data","description":"Retrieves real-time weather forecast data and converts it into\ncalendar-ready weather events.\n\nEach forecast day becomes an all-day calendar event containing:\n - temperature range\n - weather conditions\n - humidity\n - wind\n - sunrise/sunset\n - localized descriptions\n\nVisual identity and runtime emoji/color can be customized.\n\nBring your own OpenWeather key by using the `X-OpenWeather-Key` header. Use\n`/docs/handshake/weather` first when you want to verify a key from code\nwithout generating a calendar payload.\n","x-emoji":"β
","security":[{},{"OpenWeatherApiKeyHeader":[]}],"parameters":[{"in":"query","name":"city","schema":{"type":"string","default":"London","example":"Sao Paulo"},"description":"City name used for weather lookup."},{"in":"query","name":"units","schema":{"type":"string","default":"metric","enum":["metric","imperial","standard"]},"description":"Temperature and wind measurement units."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["af","ar","az","be","bg","ca","cz","da","de","el","en","es","eu","fa","fi","fr","gl","he","hi","hr","hu","id","is","it","ja","kr","ku","la","mk","nl","no","pl","pt","pt-BR","ro","ru","se","sk","sl","sq","sr","sv","th","tr","uk","vi","zh-CN","zh-TW","zu"]},"description":"Localization language for weather descriptions."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Weather calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:β
Weather\nX-WR-CALDESC:π₯οΈ 17Β° | 14Β°/17Β°\nBEGIN:VEVENT\nSUMMARY:π₯οΈ 17Β° | 14Β°/17Β°\nDESCRIPTION:β
Weather Forecast\\n\\nπ§π· SΓ£o Paulo\\n\\nπ₯οΈ Scattered clouds\\n\\nπ§ Humidity 59%\\n\\nπ© Wind speed up to 4.24 m/s\nDTSTART;VALUE=DATE:20260618\nDTEND;VALUE=DATE:20260619\nCATEGORIES:weather\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"saoPauloForecast":{"summary":"SΓ£o Paulo weather forecast","value":{"events":[{"summary":"π₯οΈ 17Β° | 14Β°/17Β°","startDate":"2026-06-18","endDate":"2026-06-19","allDay":true,"description":"Scattered clouds in SΓ£o Paulo. Humidity 59%, pressure 1023 hPa, wind 4.24 m/s from ESE.","category":"weather","calendarCategory":"weather","calendarEmoji":"β
","calendarName":"β
Weather","calendarColor":"#808080","timezone":"America/Sao_Paulo","data":{"city":"SΓ£o Paulo","country":"BR","condition":"Scattered clouds","temperature":17,"tempMin":14,"tempMax":17,"feelsLike":17,"humidity":59,"pressure":1023,"windSpeed":4.24,"windDirection":"ESE","sunrise":"06:47","sunset":"17:28"}}],"meta":{"name":"β
Weather","emoji":"β
","color":"#808080","summary":"π₯οΈ 17Β° | 14Β°/17Β°","endpoint":"weather"}}}}},"application/xml":{"schema":{"type":"string"},"example":"\n\n β
Weather\n π₯οΈ 17Β° | 14Β°/17Β°\n\n"},"text/plain":{"schema":{"type":"string"},"example":"π₯οΈ 17Β° | 14Β°/17Β°\nβ
Weather Forecast - SΓ£o Paulo\n"}}},"400":{"description":"Bad Request - Invalid city or missing parameters."},"500":{"description":"Internal Server Error - Failed to fetch or process weather data."}}}},"/docs/handshake/weather":{"get":{"tags":["Docs"],"summary":"Test an OpenWeather BYOK handshake","description":"Tests a user-supplied OpenWeather API key without returning the secret.\n\nThis endpoint is intended for developers who want to verify their key before\ncalling `/weather` from their own code. The response includes safe request\nsnippets and an upstream status summary. The canonical form is the\n`X-OpenWeather-Key` header. Query parameters carrying provider secrets are\ndisabled by default because URLs are more likely to leak through logs,\nbrowser history, observability, and shared links.\n","operationId":"weatherByokHandshake","security":[{"OpenWeatherApiKeyHeader":[]}],"parameters":[{"in":"query","name":"city","schema":{"type":"string","default":"London","example":"Sao Paulo"},"description":"City used for the upstream handshake request."},{"in":"query","name":"units","schema":{"type":"string","default":"metric","enum":["metric","imperial","standard"]},"description":"OpenWeather units used during the handshake."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","example":"pt-BR"},"description":"Language resolved for the OpenWeather request."}],"responses":{"200":{"description":"The supplied OpenWeather key worked.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"provider":{"type":"string","example":"openweather"},"purpose":{"type":"string","example":"byok-handshake"},"credential":{"type":"object","properties":{"source":{"type":"string","example":"header:x-openweather-key"},"fingerprint":{"type":"string","example":"sha256:1a2b3c4d5e6f"}}},"request":{"type":"object","properties":{"city":{"type":"string","example":"Sao Paulo"},"units":{"type":"string","example":"metric"},"lang":{"type":"string","example":"pt_br"}}},"upstream":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"status":{"type":"integer","example":200},"code":{"type":"string","example":"200"},"city":{"type":"object","additionalProperties":true},"forecastCount":{"type":"integer","example":40}}},"durationMs":{"type":"integer","example":312},"code":{"type":"object","properties":{"handshake":{"type":"string","example":"/api/docs/handshake/weather?city=Sao+Paulo&units=metric&lang=pt-BR"},"calendar":{"type":"string","example":"/api/weather?city=Sao+Paulo&units=metric&lang=pt-BR&format=json"},"curl":{"type":"string","example":"curl -H \"X-OpenWeather-Key: \" \"/api/weather?city=Sao+Paulo&units=metric&lang=pt-BR&format=json\"\n"},"javascript":{"type":"string","example":"await fetch('/api/weather?city=Sao+Paulo&units=metric&lang=pt-BR&format=json', { headers: { 'X-OpenWeather-Key': OPENWEATHER_API_KEY } })\n"}}}}}}}},"400":{"description":"Missing key or invalid handshake input."},"401":{"description":"OpenWeather rejected the supplied key."},"404":{"description":"OpenWeather could not resolve the supplied city."},"429":{"description":"OpenWeather rate limited the supplied key."},"502":{"description":"OpenWeather could not be reached or returned an upstream error."},"504":{"description":"OpenWeather handshake timed out."}}}},"/mcp":{"get":{"tags":["Docs"],"summary":"MCP endpoint metadata","description":"Returns metadata for the Super Calendar Model Context Protocol JSON-RPC endpoint.","responses":{"200":{"description":"MCP endpoint metadata","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"protocol":{"type":"string"},"endpoint":{"type":"string"},"transport":{"type":"string"},"capabilities":{"type":"object"}}}}}}}},"post":{"tags":["Docs"],"summary":"Model Context Protocol JSON-RPC endpoint","description":"Exposes Super Calendar tools, resources, and prompts over JSON-RPC for MCP-compatible clients.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"}]},"method":{"type":"string","example":"tools/list"},"params":{"type":"object"}}},{"type":"array","items":{"type":"object"}}]}}}},"responses":{"200":{"description":"JSON-RPC response","content":{"application/json":{"schema":{"type":"object"}}}},"204":{"description":"Notification accepted with no JSON-RPC response body"},"400":{"description":"Invalid JSON-RPC request"}}}},"/moon":{"get":{"tags":["Astronomy"],"summary":"Moon phases and lunar events","description":"Calculates the major lunar phases (New Moon, First Quarter,\nFull Moon, Last Quarter) for the current year.\n\nEvents are normalized according to:\n - timezone offset\n - hemisphere orientation\n - localized language strings\n\nEach moon phase is returned as a calendar-ready event.\n","x-emoji":"π","parameters":[{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"hemisphere","schema":{"type":"string","default":"south","enum":["north","south"]},"description":"Hemisphere orientation used to determine\nmoon visualization semantics.\n"},{"in":"query","name":"advanced","schema":{"type":"boolean","default":false},"description":"When true, expands the calendar from the four major lunar phases\nto the traditional eight-phase view by calculating intermediate\nphase points between the official major phases.\n"},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"year","schema":{"type":"integer","example":2026},"description":"Target year for event generation."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Moon-phase calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π Moon\nBEGIN:VEVENT\nSUMMARY:π Full Moon\nDESCRIPTION:π Moon Phases\\n\\nπ Full Moon\\n\\nHemisphere: South\nDTSTART;VALUE=DATE:20260601\nDTEND;VALUE=DATE:20260602\nCATEGORIES:astronomy\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"fullMoon":{"summary":"Full Moon phase event","value":{"events":[{"summary":"π Full Moon","startDate":"2026-06-01","endDate":"2026-06-02","allDay":true,"description":"Major lunar phase event.","category":"astronomy","calendarCategory":"moon","calendarEmoji":"π","calendarName":"π Moon","data":{"phase":"full-moon","hemisphere":"south"}}],"meta":{"name":"π Moon","emoji":"π","endpoint":"moon"}}}}}}},"500":{"description":"Internal Server Error - Failed to fetch astronomical data."}}}},"/seasons":{"get":{"tags":["Astronomy"],"summary":"Equinoxes and Solstices (Seasons)","description":"Calculates the dates and times for equinoxes and solstices of the current year.\n\nAdjusts descriptions and timings based on:\n - hemisphere orientation\n - timezone offset\n - localized language\n\nOptionally includes orbital events:\n - perihelion\n - aphelion\n\nEach season change is returned as a calendar-ready event.\n","x-emoji":"π","parameters":[{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"hemisphere","schema":{"type":"string","default":"south","enum":["north","south"]},"description":"Hemisphere used to invert season logic."},{"in":"query","name":"orbit","schema":{"type":"boolean","default":false},"description":"If enabled, includes orbital events:\n - perihelion\n - aphelion\n"},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"year","schema":{"type":"integer","example":2026},"description":"Target year for event generation."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Seasons and orbital-event calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π Seasons\nBEGIN:VEVENT\nSUMMARY:π Autumn Equinox\nDESCRIPTION:π Seasons\\n\\nπ Autumn Equinox in the southern hemisphere.\nDTSTART;VALUE=DATE:20260320\nDTEND;VALUE=DATE:20260321\nCATEGORIES:astronomy\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"autumnEquinox":{"summary":"Southern hemisphere autumn equinox","value":{"events":[{"summary":"π Autumn Equinox","startDate":"2026-03-20","endDate":"2026-03-21","allDay":true,"description":"Autumn Equinox in the southern hemisphere.","category":"astronomy","calendarCategory":"seasons","calendarEmoji":"π","calendarName":"π Seasons","data":{"season":"autumn","eventType":"equinox","hemisphere":"south"}}],"meta":{"name":"π Seasons","emoji":"π","endpoint":"seasons"}}}}}}},"500":{"description":"Internal Server Error - Failed to fetch astronomical data."}}}},"/exchange":{"get":{"tags":["Finance"],"summary":"Currency exchange rates","description":"Fetches real-time exchange rates between a base currency\nand one or more target currencies.\n\nEach exchange rate snapshot is returned as a calendar-ready event.\n","x-emoji":"π±","x-supported-currencies":["USD","AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHF","CLP","CNY","COP","CRC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","FOK","GBP","GEL","GGP","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","IMP","INR","IQD","IRR","ISK","JEP","JMD","JOD","JPY","KES","KGS","KHR","KID","KMF","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLE","SLL","SOS","SRD","SSP","STN","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TVD","TWD","TZS","UAH","UGX","UYU","UZS","VES","VND","VUV","WST","XAF","XCD","XDR","XOF","XPF","YER","ZAR","ZMW","ZWL"],"x-currency-formatting":"Intl.NumberFormat","parameters":[{"in":"query","name":"base","schema":{"type":"string","default":"USD","example":"USD"},"description":"Source currency code. Store the code and let backend internationalization format symbols and names."},{"in":"query","name":"target","schema":{"type":"string","default":"BRL,EUR","example":"BRL,EUR"},"description":"Comma-separated target currency codes. Values are accepted when returned by the exchange provider."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Exchange-rate calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π± Exchange\nBEGIN:VEVENT\nSUMMARY:π΅ USD/BRL: R$ 5.43\nDESCRIPTION:π± Exchange Rate\\n\\n1 USD = R$ 5.43 BRL\nDTSTART;VALUE=DATE:20260618\nDTEND;VALUE=DATE:20260619\nCATEGORIES:finance\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"usdBrl":{"summary":"USD to BRL exchange event","value":{"events":[{"summary":"π΅ USD/BRL: R$ 5.43","startDate":"2026-06-18","endDate":"2026-06-19","allDay":true,"description":"1 USD = R$ 5.43 BRL","category":"finance","calendarCategory":"exchange","calendarEmoji":"π±","calendarName":"π± Exchange","data":{"base":"USD","target":"BRL","rate":5.43}}],"meta":{"name":"π± Exchange","emoji":"π±","endpoint":"exchange"}}}}}}},"500":{"description":"Internal Server Error - Financial API unreachable."}}}},"/crypto":{"get":{"tags":["Finance"],"summary":"Cryptocurrency market prices","description":"Fetches real-time cryptocurrency prices (e.g., Bitcoin, Ethereum)\nagainst one or more fiat currencies.\n\nEach cryptocurrency is returned as a calendar event snapshot\ncontaining the latest market valuation.\n","x-emoji":"π","parameters":[{"in":"query","name":"ids","schema":{"type":"string","default":"bitcoin,ethereum","example":"bitcoin,ethereum"},"description":"Comma-separated CoinGecko coin IDs."},{"in":"query","name":"vs","schema":{"type":"string","default":"usd,brl","example":"usd,brl"},"description":"Comma-separated fiat currencies (e.g. usd,brl,eur)."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Cryptocurrency market calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π Crypto\nBEGIN:VEVENT\nSUMMARY:πͺ Bitcoin: $107,000.00\nDESCRIPTION:π Cryptocurrency\\n\\nBTC/USD market snapshot.\nDTSTART;VALUE=DATE:20260618\nDTEND;VALUE=DATE:20260619\nCATEGORIES:crypto\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"bitcoinUsd":{"summary":"Bitcoin market snapshot","value":{"events":[{"summary":"πͺ Bitcoin: $107,000.00","startDate":"2026-06-18","endDate":"2026-06-19","allDay":true,"description":"BTC/USD market snapshot.","category":"crypto","calendarCategory":"crypto","calendarEmoji":"π","calendarName":"π Crypto","data":{"id":"bitcoin","symbol":"BTC","vs":"USD","price":107000}}],"meta":{"name":"π Crypto","emoji":"π","endpoint":"crypto"}}}}}}},"500":{"description":"Internal Server Error - Crypto API unreachable or invalid parameters."}}}},"/earnings":{"get":{"tags":["Earnings"],"summary":"Earnings Calendar / Quarterly History","description":"Returns earnings data in two modes:\n\n1. Historical mode (when symbol is provided)\n - Returns quarterly earnings history for a specific company\n - Includes EPS, revenue, beats, surprises, and YoY growth\n\n2. Daily calendar mode (when no symbol is provided)\n - Returns upcoming earnings events grouped by market session\n (pre-market / after-market / not specified)\n\nEach result is returned as a calendar event object.\n","x-emoji":"π","parameters":[{"in":"query","name":"symbol","required":false,"schema":{"type":"string","default":"GOOGL","example":"GOOGL"},"description":"Stock ticker symbol. If provided, returns historical quarterly earnings."},{"in":"query","name":"date","required":false,"schema":{"type":"string","example":"today"},"description":"Used only for daily calendar mode."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Override calendar color."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Earnings calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π Earnings - GOOGL\nBEGIN:VEVENT\nSUMMARY:π GOOGL Earnings Q1\nDESCRIPTION:π Market Earnings\\n\\nCompany: GOOGL\\nEPS and revenue snapshot.\nDTSTART;VALUE=DATE:20260618\nDTEND;VALUE=DATE:20260619\nCATEGORIES:finance\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"googlQuarter":{"summary":"GOOGL quarterly earnings","value":{"events":[{"summary":"π GOOGL Earnings Q1","startDate":"2026-06-18","endDate":"2026-06-19","allDay":true,"description":"GOOGL quarterly earnings snapshot.","category":"finance","calendarCategory":"earnings","calendarEmoji":"π","calendarName":"π Earnings","data":{"symbol":"GOOGL","quarter":"Q1","eps":1.89,"revenue":80500000000}}],"meta":{"name":"π Earnings","emoji":"π","endpoint":"earnings"}}}}}}},"401":{"description":"Unauthorized - missing API key."},"500":{"description":"Internal Server Error - earnings provider failed."}}}},"/sports":{"get":{"tags":["Sports"],"summary":"Sports calendar hub","description":"Sports is a hub endpoint. Use a subroute for each sport so football, basketball, volleyball, and future sports can grow without one dense contract.\n","parameters":[{"name":"sport","in":"query","schema":{"type":"string","enum":["football","basketball","volleyball"],"default":"football"},"description":"Optional hub selector. Prefer the explicit subroutes below."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Calendar response for the selected sports adapter.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]}}}},"400":{"description":"Missing provider key or invalid input."},"500":{"description":"Sports provider or transformation error."}}}},"/sports/football":{"get":{"tags":["Sports"],"summary":"Football calendars and structured match data","description":"Football calendar backed by API-FOOTBALL / API-SPORTS. The public ICS surface uses stable league aliases and server-resolved current seasons, so users do not need to pin years in subscription links.\n","parameters":[{"name":"league","in":"query","schema":{"type":"string","enum":["world-cup","brasileirao","brasileirao-serie-a","uefa","champions-league"],"default":"world-cup"},"description":"Stable league alias. Numeric API-FOOTBALL ids are still accepted internally, but aliases are preferred for public links.\n"},{"name":"mode","in":"query","schema":{"type":"string","enum":["fixtures","rounds","teams","standings"],"default":"fixtures"},"description":"Data shape to request. `fixtures` returns calendar events."},{"name":"round","in":"query","schema":{"type":"string","example":"Group Stage - 1"},"description":"Optional current-season round filter."},{"name":"team","in":"query","schema":{"type":"integer"},"description":"Optional API-FOOTBALL team id filter for current-season calendars."},{"name":"status","in":"query","schema":{"type":"string","example":"1H-HT-2H-ET-P-BT-LIVE"},"description":"Optional fixture status filter for live/in-progress views."},{"name":"current","in":"query","schema":{"type":"boolean"},"description":"Optional `fixtures/rounds` current-round filter."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Football response as ICS, JSON, XML, CSV, text, or other supported format.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"worldCupFixtures":{"summary":"World Cup football calendar","value":{"events":[{"summary":"β½ π§π· Brasil x π«π· FranΓ§a"}],"meta":{"name":"Sports - World Cup 2026"},"football":{"provider":"api-football","mode":"fixtures","leagueAlias":"world-cup"}}}}},"text/calendar":{"schema":{"type":"string"}}}},"400":{"description":"Missing API-FOOTBALL key or invalid input."},"500":{"description":"Football provider or transformation error."}}}},"/sports/basketball":{"get":{"tags":["Sports"],"summary":"Basketball calendars, starting with NBA","description":"Basketball calendar backed by the API-SPORTS NBA API. The default league is NBA (`league=nba`) and the season is resolved by the server.\n","parameters":[{"name":"league","in":"query","schema":{"type":"string","enum":["nba"],"default":"nba"},"description":"Stable basketball league alias."},{"name":"mode","in":"query","schema":{"type":"string","enum":["games","teams","standings"],"default":"games"},"description":"Data shape to request. `games` returns calendar events."},{"name":"team","in":"query","schema":{"type":"integer"},"description":"Optional API-NBA team id filter for current-season calendars."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Basketball response as ICS, JSON, XML, CSV, text, or other supported format.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"nbaGames":{"summary":"NBA current-season calendar","value":{"events":[{"summary":"π Lakers x Celtics"}],"basketball":{"provider":"api-nba","leagueAlias":"nba"}}}}},"text/calendar":{"schema":{"type":"string"}}}},"400":{"description":"Missing API-NBA key or invalid input."},"500":{"description":"Basketball provider or transformation error."}}}},"/sports/volleyball":{"get":{"tags":["Sports"],"summary":"Volleyball calendars","description":"Volleyball calendar backed by API-SPORTS Volleyball. The adapter is isolated so championships can be added as aliases without making the sports hub dense.\n","parameters":[{"name":"league","in":"query","schema":{"type":"string","default":"nations-league"},"description":"Stable volleyball league alias or provider id. Configure SPORTS_VOLLEYBALL_NATIONS_LEAGUE_ID to bind the default alias.\n"},{"name":"mode","in":"query","schema":{"type":"string","enum":["games","teams","leagues","standings"],"default":"games"},"description":"Data shape to request. `games` returns calendar events."},{"name":"team","in":"query","schema":{"type":"integer"},"description":"Optional API-VOLLEYBALL team id filter."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Volleyball response as ICS, JSON, XML, CSV, text, or other supported format.","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"volleyballGames":{"summary":"Volleyball current-season calendar","value":{"events":[{"summary":"π Brazil x France"}],"volleyball":{"provider":"api-volleyball","leagueAlias":"nations-league"}}}}},"text/calendar":{"schema":{"type":"string"}}}},"400":{"description":"Missing API-VOLLEYBALL key or invalid input."},"500":{"description":"Volleyball provider or transformation error."}}}},"/religion":{"get":{"tags":["Religion"],"summary":"Religious observances and holy days","description":"Fetches religious observances from multiple faith calendars\n(Christian, Jewish, Islamic).\n\nSupports multi-religion aggregation in a single request and\nautomatically deduplicates overlapping dates.\n\nEach request returns a normalized calendar event list with runtime metadata.\n","x-emoji":"π","parameters":[{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"religion","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["christian","jewish","islamic"]},"default":["christian"]},"description":"One or more religions to include in the calendar response.\n\nExample:\n ?religion=christian&religion=islamic\n"},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Religious observance calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π Religion\nBEGIN:VEVENT\nSUMMARY:βοΈ Easter\nDESCRIPTION:π Religious Observance\\n\\nChristian observance.\nDTSTART;VALUE=DATE:20260405\nDTEND;VALUE=DATE:20260406\nCATEGORIES:religion\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"christianObservance":{"summary":"Christian observance","value":{"events":[{"summary":"βοΈ Easter","startDate":"2026-04-05","endDate":"2026-04-06","allDay":true,"description":"Christian religious observance.","category":"religion","calendarCategory":"religion","calendarEmoji":"π","calendarName":"π Religion","data":{"religion":"christian","observance":"easter"}}],"meta":{"name":"π Religion","emoji":"π","endpoint":"religion"}}}}}}},"400":{"description":"Validation error - invalid religion parameter or malformed request."},"500":{"description":"Internal Server Error - Failed to fetch or process religious data."}}}},"/events":{"get":{"tags":["Personal"],"summary":"Custom recurring events","description":"Generates recurring calendar events based on dynamic query parameters.\n\nEach query parameter (except system parameters like lang, year, tz, emoji, glyph, color and format)\nis interpreted as a recurring event rule:\n\n- parameter name = event identifier (e.g. \"rent\", \"gym\", \"internet\")\n- parameter value = day of the month (e.g. \"05\", \"15\", \"28\")\n\nThe system generates events for each month of the specified year.\n\nExample:\n ?periodic=01&studies=05&rent=10&company=15&finances=25&lang=pt\n","x-emoji":"π","parameters":[{"in":"query","name":"year","schema":{"type":"integer","example":2026},"description":"Target year for event generation. Defaults to current year."},{"in":"query","name":"tz","schema":{"type":"integer","default":0,"example":-3},"description":"Timezone offset in hours for event timestamps."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"Language for event titles and descriptions."},{"in":"query","name":"periodic","schema":{"type":"string","default":"01","example":"01"},"description":"Day of the month for periodic recurring events."},{"in":"query","name":"studies","schema":{"type":"string","default":"05","example":"05"},"description":"Day of the month for study-related recurring events."},{"in":"query","name":"rent","schema":{"type":"string","default":"10","example":"10"},"description":"Day of the month for rent."},{"in":"query","name":"company","schema":{"type":"string","default":"15","example":"15"},"description":"Day of the month for company recurring events."},{"in":"query","name":"finances","schema":{"type":"string","default":"25","example":"25"},"description":"Day of the month for finance recurring events."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default recurring event emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#e74c3c"},"description":"Overrides calendar color for all generated events."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Recurring personal-events calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π Events\nBEGIN:VEVENT\nSUMMARY:πΆ Rent\nDESCRIPTION:π Recurring personal event.\nDTSTART;VALUE=DATE:20260110\nDTEND;VALUE=DATE:20260111\nCATEGORIES:personal\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"recurringRent":{"summary":"Monthly rent event","value":{"events":[{"summary":"πΆ Rent","startDate":"2026-01-10","endDate":"2026-01-11","allDay":true,"description":"Recurring personal event.","category":"personal","calendarCategory":"events","calendarEmoji":"π","calendarName":"π Events","data":{"rule":"monthly","key":"rent","dayOfMonth":10}}],"meta":{"name":"π Events","emoji":"π","endpoint":"events"}}}}}}},"500":{"description":"Internal Server Error - Failed to process recurring event data."}}}},"/custom":{"get":{"tags":["Personal"],"summary":"Fully custom calendar events","description":"Generates fully custom calendar events from arbitrary query parameters.\n\nEach non-reserved query parameter is interpreted as a JSON string\ndescribing a calendar event.\n\nRequired fields:\n - day\n - month\n\nOptional fields:\n - name\n - emoji\n\nExample:\n ?Counter-Day={\"day\":20,\"month\":2,\"name\":\"Counter-day\",\"emoji\":\"π\"}\n","x-emoji":"π
","parameters":[{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"name","schema":{"type":"string","example":"Nerd Days"},"description":"Overrides calendar name."},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"User-defined custom calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π
Custom\nBEGIN:VEVENT\nSUMMARY:π Counter-day\nDESCRIPTION:π
Custom calendar event.\nDTSTART;VALUE=DATE:20260220\nDTEND;VALUE=DATE:20260221\nCATEGORIES:custom\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"counterDay":{"summary":"Custom Counter-day event","value":{"events":[{"summary":"π Counter-day","startDate":"2026-02-20","endDate":"2026-02-21","allDay":true,"description":"Custom calendar event.","category":"personal","calendarCategory":"custom","calendarEmoji":"π
","calendarName":"π
Custom","data":{"day":20,"month":2,"name":"Counter-day","emoji":"π"}}],"meta":{"name":"π
Custom","emoji":"π
","endpoint":"custom"}}}}}}},"400":{"description":"Invalid JSON event payload"},"500":{"description":"Internal Server Error"}}}},"/trivia":{"get":{"tags":["Entertainment"],"summary":"Historical events and trivia (On This Day)","description":"Consumes the Wikimedia \"On This Day\" API to return historical events, births, and deaths\nformatted as calendar events.\n\nSupports caching and request de-duplication for performance optimization.\n","x-emoji":"β","parameters":[{"in":"query","name":"month","schema":{"type":"integer","minimum":1,"maximum":12,"example":4},"description":"Event month (1-12).\nValues are automatically normalized with zero-padding when needed.\n"},{"in":"query","name":"day","schema":{"type":"integer","minimum":1,"maximum":31,"example":19},"description":"Event day (1-31).\nValues are automatically normalized with zero-padding when needed.\n"},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"Language used for content retrieval and UI normalization.\n\nThis affects Wikimedia query locale and text formatting.\n"},{"in":"query","name":"type","schema":{"type":"string","default":"all","enum":["all","selected","births","deaths","events","holidays"]},"description":"Filters the type of historical data returned.\n\n- all: returns all categories\n- births: only birth events\n- deaths: only death events\n- events: historical events\n- holidays: observances (if available)\n"},{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides the default emoji used in trivia event titles."},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#FF5733"},"description":"Overrides the hex color used in calendar events."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Historical trivia calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:β Trivia\nBEGIN:VEVENT\nSUMMARY:β On This Day\nDESCRIPTION:Historical event from the On This Day source.\nDTSTART;VALUE=DATE:20260419\nDTEND;VALUE=DATE:20260420\nCATEGORIES:trivia\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"onThisDay":{"summary":"Historical event","value":{"events":[{"summary":"β On This Day","startDate":"2026-04-19","endDate":"2026-04-20","allDay":true,"description":"Historical event from the On This Day source.","category":"trivia","calendarCategory":"trivia","calendarEmoji":"β","calendarName":"β Trivia","data":{"month":4,"day":19,"type":"events"}}],"meta":{"name":"β Trivia","emoji":"β","endpoint":"trivia"}}}}}}},"400":{"description":"Bad Request - Missing or invalid month/day parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid or missing date parameters"}}}}}},"500":{"description":"Internal Server Error - Wikimedia API failure or processing error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Failed to fetch trivia data"}}}}}}}}},"/holidays":{"get":{"tags":["Public Calendars"],"summary":"Global Holidays & Observances","description":"Fetches national, regional (state), and municipal (city) holidays\nfrom a compiled SQLite database.\n\nImplements a locale-first resolution strategy for multi-language\ncountries (e.g., India, Brazil).\n","x-emoji":"π","parameters":[{"in":"query","name":"country","required":true,"schema":{"type":"string","example":"BR"},"description":"REQUIRED. ISO 3166-1 alpha-2 country code."},{"in":"query","name":"state","schema":{"type":"string","example":"SP"},"description":"ISO state code or slug.\nIf provided, includes state-level holidays.\n"},{"in":"query","name":"city","schema":{"type":"string","example":"SAO_PAULO"},"description":"City slug.\nRequires `state` to be defined for correct resolution.\n\nIf provided, includes municipal holidays.\n"},{"in":"query","name":"year","schema":{"type":"integer","example":2026},"description":"Target year for event generation."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},{"in":"query","name":"emoji","schema":{"type":"boolean","default":false},"description":"When enabled, adds category and type emojis to event titles.\nExample: π§π· π New Year.\n"},{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides the default hex color used for calendar events."},{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"}],"responses":{"200":{"description":"Public holiday calendar payload.","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nX-WR-CALNAME:π Holidays\nBEGIN:VEVENT\nSUMMARY:π§π· Tiradentes\nDESCRIPTION:π Public holiday in Brazil.\nDTSTART;VALUE=DATE:20260421\nDTEND;VALUE=DATE:20260422\nCATEGORIES:holiday\nEND:VEVENT\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"examples":{"brazilHoliday":{"summary":"Brazil public holiday","value":{"events":[{"summary":"π§π· Tiradentes","startDate":"2026-04-21","endDate":"2026-04-22","allDay":true,"description":"Public holiday in Brazil.","category":"holiday","calendarCategory":"holidays","calendarEmoji":"π","calendarName":"π Holidays","data":{"country":"BR","state":"SP","city":"SAO_PAULO","scope":"national"}}],"meta":{"name":"π Holidays","emoji":"π","endpoint":"holidays"}}}}}}},"400":{"description":"Bad Request - Missing or invalid required parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Country parameter is required"}}}}}},"500":{"description":"Internal Server Error - Database or processing failure.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}}},"components":{"schemas":{"CalendarEvent":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]},"CalendarMeta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]},"CalendarResponse":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]},"WeatherHandshakeResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"provider":{"type":"string","example":"openweather"},"purpose":{"type":"string","example":"byok-handshake"},"credential":{"type":"object","properties":{"source":{"type":"string","example":"header:x-openweather-key"},"fingerprint":{"type":"string","example":"sha256:1a2b3c4d5e6f"}}},"request":{"type":"object","properties":{"city":{"type":"string","example":"Sao Paulo"},"units":{"type":"string","example":"metric"},"lang":{"type":"string","example":"pt_br"}}},"upstream":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"status":{"type":"integer","example":200},"code":{"type":"string","example":"200"},"city":{"type":"object","additionalProperties":true},"forecastCount":{"type":"integer","example":40}}},"durationMs":{"type":"integer","example":312},"code":{"type":"object","properties":{"handshake":{"type":"string","example":"/api/docs/handshake/weather?city=Sao+Paulo&units=metric&lang=pt-BR"},"calendar":{"type":"string","example":"/api/weather?city=Sao+Paulo&units=metric&lang=pt-BR&format=json"},"curl":{"type":"string","example":"curl -H \"X-OpenWeather-Key: \" \"/api/weather?city=Sao+Paulo&units=metric&lang=pt-BR&format=json\"\n"},"javascript":{"type":"string","example":"await fetch('/api/weather?city=Sao+Paulo&units=metric&lang=pt-BR&format=json', { headers: { 'X-OpenWeather-Key': OPENWEATHER_API_KEY } })\n"}}}}}},"responses":{"CalendarResponse":{"description":"Standard calendar payload","content":{"text/calendar":{"schema":{"type":"string"},"example":"BEGIN:VCALENDAR\nVERSION:2.0\nEND:VCALENDAR\n"},"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"summary":{"type":"string","example":"π
Calendar event"},"startDate":{"type":"string","description":"ISO 8601 date or datetime","example":"2026-05-08"},"endDate":{"type":"string","description":"ISO 8601 end date or datetime","example":"2026-05-08"},"allDay":{"type":"boolean","example":true},"description":{"type":"string","example":"Calendar-ready event generated from a Super Calendar source."},"category":{"type":"string","example":"calendar"},"calendarCategory":{"type":"string","example":"calendar"},"calendarEmoji":{"type":"string","example":"π
"},"calendarName":{"type":"string","example":"Calendar Feed"},"calendarColor":{"type":"string","example":"#808080"},"timezone":{"type":"string","example":"UTC"},"data":{"type":"object","description":"Integration-specific structured event data.","additionalProperties":true},"intl":{"type":"object","description":"Backend internationalization payloads, such as formatted currency, number, date, or locale data.","additionalProperties":true}},"required":["summary","startDate","endDate"]}},"meta":{"type":"object","properties":{"name":{"type":"string","example":"Calendar Feed"},"emoji":{"type":"string","example":"π
"},"color":{"type":"string","example":"#808080"},"summary":{"type":"string","example":"Calendar-ready events"},"endpoint":{"type":"string","example":"calendar"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["name"]}},"required":["events","meta"]}},"application/xml":{"schema":{"type":"string"},"example":"\n\n \n Weather\n \n \n \n Sunny\n \n \n\n"},"text/plain":{"schema":{"type":"string"},"example":"+======================================================================+\n| Super-Calendar.io |\n+----------------------------------------------------------------------+\n| Runtime Agenda - 2026-05-25 |\n+----------------------------------------------------------------------+\n| 2026-05-25 | Sunny |\n+----------------------------------------------------------------------+\n| Next: Sunny at 2026-05-25 |\n+======================================================================+\n"}}}},"parameters":{"LangParam":{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["en","pt","es","fr","de"]},"description":"UI and content language."},"TZParam":{"in":"query","name":"tz","schema":{"type":"integer","default":0},"description":"Timezone offset in hours from UTC."},"EmojiParam":{"in":"query","name":"emoji","schema":{"type":"string"},"description":"Overrides default calendar emoji."},"GlyphParam":{"in":"query","name":"glyph","schema":{"type":"string","example":"true"},"description":"Enables low-level calendar glyph identity. Use `glyph=true` to use the\nendpoint glyph from the feature manifest, `glyph=false` to disable it,\nor pass a single custom glyph.\n"},"ColorParam":{"in":"query","name":"color","schema":{"type":"string","example":"#3498db"},"description":"Overrides calendar color."},"YearParam":{"in":"query","name":"year","schema":{"type":"integer","example":2026},"description":"Target year for event generation."},"FormatParam":{"in":"query","name":"format","schema":{"type":"string","default":"ics","enum":["ics","json","xml","text","ansi","html","csv","tsv","ndjson","jsonl"]},"description":"Response format. Calendar subscriptions use `ics` by default. Use `json`\nfor API payloads, `xml` for XML-friendly parsing, `text` for\nline-oriented node text, `ansi` for terminal-colored text, `html` for\nbrowser-readable output, `csv`/`tsv` for tabular export, or\n`ndjson`/`jsonl` for line-oriented batch output.\n"},"OpenWeatherKeyQueryParam":{"in":"query","name":"openweather_key","x-header-name":"X-OpenWeather-Key","x-ui-hidden":true,"required":false,"schema":{"type":"string","format":"password"},"description":"Optional user-owned OpenWeather API key for one-off Swagger/manual tests.\nPrefer the `X-OpenWeather-Key` header in all production code. Do not store,\nshare, bookmark, or publish URLs containing this query parameter.\n"}},"securitySchemes":{"OpenWeatherApiKeyHeader":{"type":"apiKey","in":"header","name":"X-OpenWeather-Key","description":"User-owned OpenWeather API key. Preferred for BYOK calls."},"OpenWeatherApiKeyQuery":{"type":"apiKey","in":"query","name":"openweather_key","description":"Testing-only OpenWeather API key query parameter. Prefer X-OpenWeather-Key; do not store, share, bookmark, or publish URLs containing provider secrets."}}}}