# LiveCal

> LiveCal is the live layer for calendars: a publisher creates a Source for an event, visitors Track it (a real Google/Apple calendar event is written to their account), and when the publisher pushes an update LiveCal PATCHes the live event on every subscriber's calendar within seconds — not an ICS file re-polled tomorrow. This file indexes the publisher/developer integration surface for humans and agents.

## Integrate (start here)

- [Publisher Hub](https://livecal.ai/publisher): why to integrate, what it looks like, and how it works.
- [Quickstart](https://livecal.ai/publisher/quickstart): zero to a working Track button in five minutes — mint a widget key, drop two lines of HTML, create the Source it points at.
- [Publisher API reference](https://livecal.ai/publisher/docs): authentication, create a Source, push live-state, manifests & confidence tiers, the error contract, and analytics.
- [Libraries](https://livecal.ai/publisher/libraries): the `<livecal-track>` Widget embed, the WordPress plugin, the MCP server for agents, and plain REST.

## For agents

- MCP server: `POST https://livecal.ai/api/mcp` — JSON-RPC 2.0 over Streamable HTTP (JSON mode), app-scoped bearer JWT. `initialize`, `tools/list`, `tools/call`.
- MCP tools: `upsert_source`, `push_state`, `validate_source`, `get_source`, `get_stats`. Each carries a full JSON-Schema inputSchema (read it from `tools/list`); each is a thin wrapper over the REST routes below.
- Auth: exchange a site key for a JWT at `POST https://livecal.ai/api/v1/auth/token` with `{ "grant_type": "site_key", "api_key": "livecal_sk_…" }`, then send `Authorization: Bearer <jwt>`. Site keys are app-scoped (no user_email).
- Errors are stable and machine-readable on both MCP and REST: `{ code, message, retryable, field? }`. Retryable = 429/5xx (honor Retry-After); terminal = 4xx/422. MCP tool failures come back as a tool result with `isError:true` carrying the same envelope.
- Full agent bootstrap (token → tools/list → tools/call): https://livecal.ai/publisher/libraries#mcp

## REST API (Publisher Source API, live in production)

- `PUT  https://livecal.ai/api/v1/sources/{external_id}` — upsert a Source, idempotent on your external_id.
- `POST https://livecal.ai/api/v1/sources/batch` — upsert up to 100 Sources, partial-success per row.
- `POST https://livecal.ai/api/v1/sources/{id}/state` — push a live-state update (debounced; only material changes fan out to calendars).
- `POST https://livecal.ai/api/v1/sources/validate` — dry-run a Source payload (shape + time fields); no writes.
- `GET  https://livecal.ai/api/v1/sources/{id}` — read a Source's current state, facts, and feed flags.
- `GET  https://livecal.ai/api/v1/apps/{id}/stats` and `/funnel` — aggregate, PII-free analytics (buckets under 5 trackers are suppressed; k-anonymity).

## Notes

- Vocabulary: Source (the publisher object behind an event), Track/tracker (a subscriber's calendar event), Widget (`<livecal-track>`), Site key (`livecal_sk_`, server-only), Widget key (`livecal_pk_`, public, embeddable), Management PAT (`livecal_pat_`, headless console management), Facts (structured key/value with `confidence: known|provisional`), Live state (the day-of status line).
- The `manifest` slug is stored as sent; it is not yet validated against a catalog.
- Placeholders only — never inline a real key. Request a per-site key out-of-band.