API & MCP

Everything a person can do on Free Event Calendar Finder, a program or AI agent can do with the same inputs and get the identical result.

HTTP API

POST https://hearthfreeevents.usefulweb.site/api/v1/calculate – run Free Event Calendar Finder
GET https://hearthfreeevents.usefulweb.site/api/v1/tool – inputs, output schema, examples
OpenAPI 3.1: /openapi.json · /openapi.yaml
Errors: application/problem+json; 422 includes per-field errors.

Free Event Calendar Finder

Combine your own ICS files or public feed URLs, process IANA time zones and bounded daily, weekly, monthly and yearly recurrence, and export sourced event occurrences.

Inputs of Free Event Calendar Finder
Field	Type	Default	Description
`calendar`	textarea	"BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nUID:demo-1\nDTSTART:20261107T100000	Calendar (.ics text)
`calendarUrl`	url	—	Public .ics feed URL (optional)
`feeds`	textarea	—	Additional public .ics URLs (one per line)
`from`	date	"2026-11-01"	From
`to`	date	"2026-12-01"	To
`timeZone`	text	"Europe/Berlin"	Display / floating-time zone
`query`	textarea	—	Words in title or description
`freeOnly`	boolean	true	Only explicitly free events

Example request

Try an example

curl -X POST https://hearthfreeevents.usefulweb.site/api/v1/calculate -H 'content-type: application/json' -d '{}'

Every result contains

inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.

MCP (Model Context Protocol)

Streamable HTTP endpoint: https://hearthfreeevents.usefulweb.site/mcp – protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake).
Tools: hearth_free_events
Local stdio connector: node src/mcp-stdio.ts --tool=hearth-free-events

{
  "mcpServers": {
    "hearth-free-events": { "type": "http", "url": "https://hearthfreeevents.usefulweb.site/mcp" }
  }
}