{"openapi":"3.1.2","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"Super Calendar API","version":"2.0.0","description":"Dynamic temporal data infrastructure.\n\nRead the [human guides](/api/docs/guides) for concepts and onboarding.\n","x-documentation-locales":{"default":"en","available":[{"locale":"en","url":"/api/docs/json"},{"locale":"pt-BR","url":"/api/docs/json?lang=pt-BR","overlay":"./overlays/i18n/pt-BR.overlay.yaml"}]}},"externalDocs":{"description":"Human API guides and onboarding.","url":"/api/docs/guides"},"servers":[{"url":"/api"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Application health status","operationId":"getHealth","security":[],"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","operationId":"getPublicStatus","security":[],"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","stale","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"]}}}}}}},"/legacy":{"get":{"tags":["Legacy"],"summary":"Legacy compatibility contract","operationId":"getLegacyContract","security":[],"description":"Returns the machine-readable contract for the narrow legacy compatibility\nsurface. Legacy is read-only, allowlisted, and intended for clients that need\ncompact text projections or the fixed IE11/MSHTML calendar at `/calendar/`.\n\nNew integrations should prefer OpenAPI or I/O.\n","responses":{"200":{"description":"Legacy compatibility contract.","content":{"application/json":{"schema":{"type":"object","properties":{"schema":{"type":"string","example":"super-calendar.legacy.v1"},"name":{"type":"string"},"docs":{"type":"string","example":"/legacy/"},"subdomain":{"type":"string","example":"https://legacy.super-calendar.io"},"recommended":{"type":"object","additionalProperties":{"type":"string"}},"constraints":{"type":"object","additionalProperties":true},"routes":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"method":{"type":"string"},"contentType":{"type":"string"},"description":{"type":"string"}}}}},"required":["schema","name","docs","routes"]}}}}}}},"/weather":{"get":{"tags":["Weather"],"summary":"Current weather and forecast data","operationId":"getWeather","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":"β
","x-codeSamples":[{"lang":"JavaScript","label":"Fetch weather calendar JSON","source":"const url = new URL('https://super-calendar.io/api/weather');\nurl.searchParams.set('city', 'Sao Paulo');\nurl.searchParams.set('units', 'metric');\nurl.searchParams.set('lang', 'pt-BR');\nurl.searchParams.set('format', 'json');\n\nconst response = await fetch(url, {\n headers: {\n Accept: 'application/json'\n // 'X-OpenWeather-Key': process.env.OPENWEATHER_API_KEY\n }\n});\n\nif (!response.ok) {\n throw new Error(`Weather request failed: ${response.status}`);\n}\n\nconst calendar = await response.json();\nconsole.log(calendar.events?.[0]?.summary || calendar);\n"},{"lang":"Python","label":"Fetch weather calendar JSON","source":"from urllib.parse import urlencode\nfrom urllib.request import Request, urlopen\nimport json\nimport os\n\nparams = urlencode({\n \"city\": \"Sao Paulo\",\n \"units\": \"metric\",\n \"lang\": \"pt-BR\",\n \"format\": \"json\",\n})\n\nrequest = Request(\n f\"https://super-calendar.io/api/weather?{params}\",\n headers={\n \"Accept\": \"application/json\",\n # \"X-OpenWeather-Key\": os.environ[\"OPENWEATHER_API_KEY\"],\n },\n)\n\nwith urlopen(request, timeout=15) as response:\n calendar = json.loads(response.read().decode(\"utf-8\"))\n\nprint((calendar.get(\"events\") or [{}])[0].get(\"summary\", calendar))\n"}],"security":[{},{"OpenWeatherApiKeyHeader":[]}],"parameters":[{"in":"query","name":"city","schema":{"type":"string","example":"Sao Paulo"},"description":"City name used for weather lookup. Defaults to London only when no location parameter is supplied. Mutually exclusive with `lat` and `lon`."},{"in":"query","name":"lat","schema":{"type":"number","format":"double","minimum":-90,"maximum":90,"example":-23.5505},"description":"Latitude for coordinate lookup. Requires `lon` and cannot be combined with `city`."},{"in":"query","name":"lon","schema":{"type":"number","format":"double","minimum":-180,"maximum":180,"example":-46.6333},"description":"Longitude for coordinate lookup. Requires `lat` and cannot be combined with `city`."},{"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","cs","da","de","el","en","es","eu","fa","fi","fr","gl","he","hi","hr","hu","id","is","it","ja","kk","ko","ku","la","lt","mk","nl","no","pl","pt-BR","pt","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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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."}},"x-example":"/api/weather?city=Sao%20Paulo&units=metric&lang=pt-BR&emoji=true&format=xml","x-example-url":"/api/weather?example=true"}},"/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","enum":["en"]},"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","operationId":"getMcpMetadata","security":[],"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","operationId":"invokeMcp","security":[],"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"}}}},"/gateway/interaction":{"get":{"tags":["Agents"],"summary":"Interaction gateway","operationId":"getInteractionGateway","security":[],"description":"Deterministic interaction gateway for agent and menu surfaces. This route is beta; read `/agents/gateway.schema.json` before relying on it.","parameters":[{"in":"query","name":"text","schema":{"type":"string"},"description":"User-visible command or interaction text."},{"in":"query","name":"message","schema":{"type":"string"},"description":"Alternative interaction text field."},{"in":"query","name":"input","schema":{"type":"string"},"description":"Alternative low-level input field."},{"in":"query","name":"callbackData","schema":{"type":"string"},"description":"Callback payload from menu or bot surfaces."},{"in":"query","name":"format","schema":{"type":"string","enum":["json","text","txt","telegram"],"default":"json"},"description":"Response projection."}],"responses":{"200":{"description":"Gateway response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/plain":{"schema":{"type":"string"}}}}}},"post":{"tags":["Agents"],"summary":"Interaction gateway","operationId":"submitInteractionGateway","security":[],"description":"Deterministic interaction gateway for structured agent, bot, and menu payloads.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","description":"Surface sending the interaction."},"text":{"type":"string","description":"User-visible command or interaction text."},"input":{"type":"string","description":"Alternative low-level input field."},"callbackData":{"type":"string","description":"Callback payload from menu or bot surfaces."},"locale":{"type":"string"},"spaceSlug":{"type":"string"},"format":{"type":"string","enum":["json","text","txt","telegram"],"default":"json"}},"additionalProperties":true}}}},"responses":{"200":{"description":"Gateway response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/plain":{"schema":{"type":"string"}}}}}}},"/moon":{"get":{"tags":["Astronomy"],"summary":"Moon phases and lunar events","operationId":"getMoonPhases","security":[],"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":["af","ar","az","be","bg","ca","cs","da","de","el","en","es","eu","fa","fi","fr","gl","he","hi","hr","hu","id","is","it","ja","kk","ko","ku","la","lt","mk","nl","no","pl","pt-BR","pt","ro","ru","se","sk","sl","sq","sr","sv","th","tr","uk","vi","zh-CN","zh-TW","zu"]},"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","minimum":1583,"maximum":9999,"example":2026},"description":"Target Gregorian year for event generation. When omitted, the runtime\nuses the current UTC year. Endpoints backed by annual data may expose the\nyears currently published as an enum in the generated OpenAPI document.\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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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."}},"x-example":"/api/moon?year=2026&hemisphere=south&lang=ar&emoji=true&format=ics","x-example-url":"/api/moon?example=true"}},"/seasons":{"get":{"tags":["Astronomy"],"summary":"Equinoxes and Solstices (Seasons)","operationId":"getSeasons","security":[],"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":["af","ar","az","be","bg","ca","cs","da","de","el","en","es","eu","fa","fi","fr","gl","he","hi","hr","hu","id","is","it","ja","kk","ko","ku","la","lt","mk","nl","no","pl","pt-BR","pt","ro","ru","se","sk","sl","sq","sr","sv","th","tr","uk","vi","zh-CN","zh-TW","zu"]},"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","minimum":1583,"maximum":9999,"example":2026},"description":"Target Gregorian year for event generation. When omitted, the runtime\nuses the current UTC year. Endpoints backed by annual data may expose the\nyears currently published as an enum in the generated OpenAPI document.\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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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."}},"x-example":"/api/seasons?year=2026&hemisphere=south&orbit=true&lang=ru&glyph=true&format=txt","x-example-url":"/api/seasons?example=true"}},"/exchange":{"get":{"tags":["Finance"],"summary":"Latest available currency exchange rates","operationId":"getExchangeRates","security":[],"description":"Fetches the latest provider exchange-rate snapshot between a base currency\nand one or more target currencies.\n\nEach exchange rate snapshot is returned as a calendar-ready event.\nThe quote direction is always `1 BASE = rate TARGET`. For example,\n`base=USD&target=BRL` with a rate of `5.19` means `1 USD = 5.19 BRL`;\nreversing the parameters returns the reciprocal quote. JSON preserves the\nprovider value while human-readable strings use locale-aware `Intl`\ncurrency formatting.\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","x-rate-direction":"1 BASE = rate TARGET","parameters":[{"in":"query","name":"base","schema":{"type":"string","default":"USD","example":"USD"},"description":"Source currency code. This is the unit amount on the left side of `1 BASE = rate TARGET`."},{"in":"query","name":"target","schema":{"type":"string","default":"BRL,EUR","example":"BRL,EUR"},"description":"Comma-separated quote currency codes. Returned values are amounts of each target currency for one unit of the base currency. Provider-supported ISO 4217 codes are accepted even when they are not listed in the documentation hint."},{"in":"query","name":"date","schema":{"type":"string","format":"date","example":"2026-06-19"},"description":"Optional historical reference-rate date in `YYYY-MM-DD`. Historical requests use the Frankfurter reference provider; omit it for the latest available snapshot."},{"in":"query","name":"lang","schema":{"type":"string","default":"en","enum":["af","ar","az","be","bg","ca","cs","da","de","el","en","es","eu","fa","fi","fr","gl","he","hi","hr","hu","id","is","it","ja","kk","ko","ku","la","lt","mk","nl","no","pl","pt-BR","pt","ro","ru","se","sk","sl","sq","sr","sv","th","tr","uk","vi","zh-CN","zh-TW","zu"]},"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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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"}}}}}}},"400":{"description":"Request failed. Machine-readable formats return a stable error code and localization key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","example":"EXCHANGE_INVALID_DATE"},"messageKey":{"type":"string","example":"errors.exchange.invalidDate"},"details":{"type":"object","additionalProperties":true}},"required":["code","messageKey"]}},"required":["success","error"]}},"application/xml":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Request failed. Machine-readable formats return a stable error code and localization key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","example":"EXCHANGE_INVALID_DATE"},"messageKey":{"type":"string","example":"errors.exchange.invalidDate"},"details":{"type":"object","additionalProperties":true}},"required":["code","messageKey"]}},"required":["success","error"]}},"application/xml":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}}},"x-example":"/api/exchange?base=USD&target=BRL&lang=en&emoji=false&format=json","x-example-url":"/api/exchange?example=true"}},"/crypto":{"get":{"tags":["Finance"],"summary":"Cryptocurrency market prices","operationId":"getCryptoPrices","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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."}},"x-example":"/api/crypto?ids=bitcoin&vs=brl&lang=pt-BR&format=tsv","x-example-url":"/api/crypto?example=true"}},"/earnings":{"get":{"tags":["Earnings"],"summary":"Earnings Calendar / Quarterly History","operationId":"getEarnings","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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."}},"x-example":"/api/earnings?date=2026-06-20&lang=fr&format=html","x-example-url":"/api/earnings?example=true"}},"/sports":{"get":{"tags":["Sports"],"summary":"Sports calendar hub","operationId":"getSports","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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","operationId":"getFootball","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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","operationId":"getBasketball","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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","operationId":"getVolleyball","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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","operationId":"getReligiousObservances","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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."}},"x-example":"/api/religion?religion=jewish&lang=he&format=jsonl","x-example-url":"/api/religion?example=true"}},"/events":{"get":{"tags":["Personal"],"summary":"Custom recurring events","operationId":"getRecurringEvents","security":[],"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":["af","ar","az","be","bg","ca","cs","da","de","el","en","es","eu","fa","fi","fr","gl","he","hi","hr","hu","id","is","it","ja","kk","ko","ku","la","lt","mk","nl","no","pl","pt-BR","pt","ro","ru","se","sk","sl","sq","sr","sv","th","tr","uk","vi","zh-CN","zh-TW","zu"]},"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","operationId":"getCustomEvents","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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)","operationId":"getTrivia","security":[],"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":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"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","operationId":"getHolidays","security":[],"description":"Fetches national, regional (state), and municipal (city) holidays\nfrom compiled SQLite databases sharded by year and country.\n\nWhen `year` is omitted, the runtime always selects the current UTC year.\nExplicit years never fall back to a different annual shard; an unpublished\nyear is reported as unavailable instead of returning data from 2026.\n\nImplements a locale-first resolution strategy for multi-language\ncountries (e.g., India, Brazil).\n","x-runtime-data-store":"holidays","x-emoji":"π","parameters":[{"in":"query","name":"country","required":true,"schema":{"type":"string","pattern":"^[A-Z]{2}$","example":"BR","enum":["AD","AE","AF","AG","AL","AM","AO","AR","AT","AU","AZ","BB","BD","BE","BF","BG","BH","BI","BJ","BN","BO","BR","BS","BT","BW","BY","BZ","CA","CD","CG","CH","CI","CL","CM","CN","CO","CR","CU","CV","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","ER","ES","ET","FI","FJ","FM","FR","GA","GB","GD","GE","GH","GM","GN","GQ","GR","GT","GY","HN","HR","HT","HU","ID","IE","IL","IN","IQ","IR","IS","IT","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MG","MH","MK","ML","MM","MN","MR","MT","MU","MV","MW","MX","MY","MZ","NA","NE","NG","NI","NL","NO","NP","NR","NZ","OM","PA","PE","PG","PH","PK","PL","PS","PT","PW","PY","QA","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SI","SK","SL","SM","SN","SO","SR","SS","ST","SV","SY","SZ","TD","TG","TH","TJ","TL","TM","TN","TO","TR","TT","TV","TZ","UA","UG","US","UY","UZ","VC","VE","VN","VU","WS","YE","ZA","ZM","ZW"]},"description":"REQUIRED. ISO 3166-1 alpha-2 country code. The published OpenAPI\ndocument populates this field from the country databases actually\navailable at runtime, so documentation clients can render a select\nwithout promising an unavailable country.\n"},{"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","minimum":1583,"maximum":9999,"example":2026,"enum":[2026]},"description":"Target Gregorian year for event generation. When omitted, the runtime\nuses the current UTC year. Endpoints backed by annual data may expose the\nyears currently published as an enum in the generated OpenAPI document.\n","x-current-year":2026,"x-current-year-published":true},{"in":"query","name":"lang","required":false,"x-ui-allow-omit":true,"schema":{"type":"string","enum":["af","ar","az","be","bg","ca","cs","da","de","el","en","es","eu","fa","fi","fr","gl","he","hi","hr","hu","id","is","it","ja","kk","ko","ku","la","lt","mk","nl","no","pl","pt-BR","pt","ro","ru","se","sk","sl","sq","sr","sv","th","tr","uk","vi","zh-CN","zh-TW","zu"]},"description":"Optional UI and content language override. When omitted, the calendar\nuses the local language recorded for the requested country, state, or\ncity (for example, Chinese for `country=CN` and Portuguese for\n`country=BR`). In the interactive Runtime, select `--` to remove the\n`lang` query parameter and test this database-local behavior.\n"},{"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"},{"name":"example","in":"query","required":false,"x-ui-hidden":true,"description":"Serve the static example snapshot for this endpoint. No provider call is made.","schema":{"type":"boolean","default":false}}],"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":{"text/plain":{"schema":{"type":"string","example":"Missing required query parameter: country"}}}},"404":{"description":"The requested country/year SQLite shard is not published.","content":{"text/plain":{"schema":{"type":"string","example":"Error: SQLite database not found for country \"BR\" and year 2027. Available years: 2026."}}}},"500":{"description":"Internal Server Error - Database or processing failure.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}},"x-example":"/api/holidays?country=BR&year=2026&lang=es&format=csv","x-example-url":"/api/holidays?example=true"}},"/languages":{"get":{"tags":["Languages"],"summary":"Daily lexical language entry","operationId":"getLanguages","security":[],"x-runtime-data-store":"languages","description":"Returns a calendar-ready daily lexical entry for the requested language.\n\n`language` selects the language of the lexical content. `lang` independently\nselects the language used for response labels and descriptions.\n","x-emoji":"π¬","parameters":[{"in":"query","name":"language","required":true,"schema":{"type":"string","enum":["de","en","es","fr","kk","pt","ru","uk"],"example":"kk"},"description":"REQUIRED. Language of the lexical content. Available values are derived\nfrom the published per-language SQLite catalog.\n"},{"in":"query","name":"lang","required":false,"x-ui-allow-omit":true,"schema":{"type":"string","enum":["ar","de","en","es","fa","fi","fr","he","hi","it","ja","kk","ko","nl","pl","pt-BR","pt","ru","sv","tr","uk","zh-CN","zh-TW"]},"description":"Language used for response labels and descriptions. When omitted, the\ncontent language selected by `language` is used.\n"},{"in":"query","name":"set","schema":{"type":"string","default":"100","example":"100","enum":["100","set:de:word-100:v1","set:en:word-100:v1","set:es:word-100:v1","set:fr:word-100:v1","set:kk:word-100:v1","set:pt:word-100:v1","set:ru:word-100:v1","set:uk:word-100:v1","word-100"]},"description":"Lexical set name or alias used to select the daily entry. Supported\nvalues are derived from the selected language database.\n","x-values-by-language":{"de":["100","set:de:word-100:v1","word-100"],"en":["100","set:en:word-100:v1","word-100"],"es":["100","set:es:word-100:v1","word-100"],"fr":["100","set:fr:word-100:v1","word-100"],"kk":["100","set:kk:word-100:v1","word-100"],"pt":["100","set:pt:word-100:v1","word-100"],"ru":["100","set:ru:word-100:v1","word-100"],"uk":["100","set:uk:word-100:v1","word-100"]}},{"in":"query","name":"version","schema":{"type":"string","enum":["1.0.0"]},"description":"Optional version of the selected lexical set. Supported values are\nderived from the selected language database.\n","x-values-by-language":{"de":["1.0.0"],"en":["1.0.0"],"es":["1.0.0"],"fr":["1.0.0"],"kk":["1.0.0"],"pt":["1.0.0"],"ru":["1.0.0"],"uk":["1.0.0"]}},{"in":"query","name":"date","schema":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-07-31"},"description":"Calendar date used for deterministic daily selection, in YYYY-MM-DD format."},{"in":"query","name":"writingSystem","schema":{"type":"string","enum":["Arab","Cyrl","Latn","ws:de:Latn:official-2024","ws:en:Latn:modern","ws:es:Latn:standard","ws:fr:Latn:modern","ws:kk:Arab:regional-reference","ws:kk:Cyrl:modern","ws:kk:Latn:reference-2021","ws:pt:Latn:ao90","ws:ru:Cyrl:standard","ws:uk:Cyrl:standard-2026"]},"description":"Writing-system identifier or script alias used to select the lexical\nform. Supported values depend on `language`.\n","x-values-by-language":{"de":["Latn","ws:de:Latn:official-2024"],"en":["Latn","ws:en:Latn:modern"],"es":["Latn","ws:es:Latn:standard"],"fr":["Latn","ws:fr:Latn:modern"],"kk":["Arab","Cyrl","Latn","ws:kk:Arab:regional-reference","ws:kk:Cyrl:modern","ws:kk:Latn:reference-2021"],"pt":["Latn","ws:pt:Latn:ao90"],"ru":["Cyrl","ws:ru:Cyrl:standard"],"uk":["Cyrl","ws:uk:Cyrl:standard-2026"]}},{"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":"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"}}},"400":{"description":"Request failed. Machine-readable formats return a stable error code and localization key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","example":"EXCHANGE_INVALID_DATE"},"messageKey":{"type":"string","example":"errors.exchange.invalidDate"},"details":{"type":"object","additionalProperties":true}},"required":["code","messageKey"]}},"required":["success","error"]}},"application/xml":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"Request failed. Machine-readable formats return a stable error code and localization key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","example":"EXCHANGE_INVALID_DATE"},"messageKey":{"type":"string","example":"errors.exchange.invalidDate"},"details":{"type":"object","additionalProperties":true}},"required":["code","messageKey"]}},"required":["success","error"]}},"application/xml":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}},"500":{"description":"Request failed. Machine-readable formats return a stable error code and localization key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","example":"EXCHANGE_INVALID_DATE"},"messageKey":{"type":"string","example":"errors.exchange.invalidDate"},"details":{"type":"object","additionalProperties":true}},"required":["code","messageKey"]}},"required":["success","error"]}},"application/xml":{"schema":{"type":"string"}},"application/x-ndjson":{"schema":{"type":"string"}},"text/plain":{"schema":{"type":"string"}}}}}}}},"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","minimum":1583,"maximum":9999,"example":2026},"description":"Target Gregorian year for event generation. When omitted, the runtime\nuses the current UTC year. Endpoints backed by annual data may expose the\nyears currently published as an enum in the generated OpenAPI document.\n"},"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."}}},"x-runtime-data-stores":{"scope":"public-read-only","holidays":{"engine":"sqlite","topology":"year-country-sharded","databaseCount":191,"countryCount":191,"yearCount":1,"availableYears":[2026],"currentYear":2026,"currentYearAvailable":true,"countriesByYear":{"2026":["AD","AE","AF","AG","AL","AM","AO","AR","AT","AU","AZ","BB","BD","BE","BF","BG","BH","BI","BJ","BN","BO","BR","BS","BT","BW","BY","BZ","CA","CD","CG","CH","CI","CL","CM","CN","CO","CR","CU","CV","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","ER","ES","ET","FI","FJ","FM","FR","GA","GB","GD","GE","GH","GM","GN","GQ","GR","GT","GY","HN","HR","HT","HU","ID","IE","IL","IN","IQ","IR","IS","IT","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MG","MH","MK","ML","MM","MN","MR","MT","MU","MV","MW","MX","MY","MZ","NA","NE","NG","NI","NL","NO","NP","NR","NZ","OM","PA","PE","PG","PH","PK","PL","PS","PT","PW","PY","QA","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SI","SK","SL","SM","SN","SO","SR","SS","ST","SV","SY","SZ","TD","TG","TH","TJ","TL","TM","TN","TO","TR","TT","TV","TZ","UA","UG","US","UY","UZ","VC","VE","VN","VU","WS","YE","ZA","ZM","ZW"]},"countryCountByYear":{"2026":191}},"languages":{"engine":"sqlite","topology":"language-sharded","databaseCount":8,"contentLanguages":["de","en","es","fr","kk","pt","ru","uk"],"setsByLanguage":{"de":["100","set:de:word-100:v1","word-100"],"en":["100","set:en:word-100:v1","word-100"],"es":["100","set:es:word-100:v1","word-100"],"fr":["100","set:fr:word-100:v1","word-100"],"kk":["100","set:kk:word-100:v1","word-100"],"pt":["100","set:pt:word-100:v1","word-100"],"ru":["100","set:ru:word-100:v1","word-100"],"uk":["100","set:uk:word-100:v1","word-100"]},"versionsByLanguage":{"de":["1.0.0"],"en":["1.0.0"],"es":["1.0.0"],"fr":["1.0.0"],"kk":["1.0.0"],"pt":["1.0.0"],"ru":["1.0.0"],"uk":["1.0.0"]},"writingSystemsByLanguage":{"de":["Latn","ws:de:Latn:official-2024"],"en":["Latn","ws:en:Latn:modern"],"es":["Latn","ws:es:Latn:standard"],"fr":["Latn","ws:fr:Latn:modern"],"kk":["Arab","Cyrl","Latn","ws:kk:Arab:regional-reference","ws:kk:Cyrl:modern","ws:kk:Latn:reference-2021"],"pt":["Latn","ws:pt:Latn:ao90"],"ru":["Cyrl","ws:ru:Cyrl:standard"],"uk":["Cyrl","ws:uk:Cyrl:standard-2026"]}}}}