# SceneF

> Every movie showtime in San Francisco — chains, indies, and repertory houses —
> in one place, re-verified against each theater's own calendar twice a day.
> Built to be
> read by people and by agents; everything below is open, no key required.

The data promise: every screening is fetched from the theater's own ticketing
system or calendar where the house lets a machine read it, and from a
licensed listings feed for the chains that do not — every record says which,
and is re-verified twice a day. Each record carries its provenance
and the build timestamp (data_as_of). If we can't verify a theater, /status says so.

Accuracy is computed and published, never asserted. Every screening carries a
confidence level (venue-published, corroborated, single-source, disputed), a
source_tier (venue-api, public-feed, verified-scrape, licensed-feed), the sources
that reported it, and verified_at. Our own verification record — checks run,
checks confirmed, checks that disagreed, checks that could not run — is public at
/api/accuracy, site-wide and per venue. A check blocked by a bot wall is graded
unreachable and excluded from the pass rate rather than counted as a pass, and
the pass rate reads null rather than 100% when nothing gradeable has run. Chain
showtimes (AMC, Regal, Apple Cinemas) are licensed from an aggregator rather than
read first-hand; they are labeled licensed-feed and carry the weakest claim here.

## URL grammar (pages)

- / — tonight, every screen in the city
- /week — the next seven nights, grouped by night
- /film/{slug} — one film (e.g. /film/the-matrix-1999): showtimes, trailer, where it's playing
- /theater/{venueId} — one house (e.g. /theater/roxie): calendar, discounts, details
- /theaters, /agents, /status, /methodology — the venue list, this guide as a page, feed health, how the data is made

Bring-your-own-profile params work on listing pages and API slices; nothing is
stored server-side: likes=horror,thriller · no=musical,matinee · window=matinee|early|evening|late ·
home=roxie,balboa · formats=35mm,imax · discounts=only.
Everything ranks; discounts=only is the one param that filters.
Ranking is pure preference-scoring — nothing hidden, nothing pay-ranked.

Content negotiation: request /, /week, /film/{slug}, or /theater/{venueId} with
an Accept header of application/json or text/markdown (and no text/html) and you
get the same content as structured JSON or clean markdown instead of a page.

## APIs (all GET, CORS open, JSON)

- /api/listings — the canonical feed: venues, films, screenings (each with confidence, source_tier, sources, verified_at). Slices: ?venue={id} ?night=YYYY-MM-DD ?film={slug} ?when=tonight|week. Add compact=1 when your tool harness truncates large payloads. ETagged.
- /api/listings → notable.items — tonight's scarcity FACTS, citywide, never taste: selling-fast (measured seat counts, self-dated), last-night (the venue's own forward calendar proves the film is done), only-print (the night's lone listed 35mm/70mm/16mm), cheap-night (posted day-bound price), live-event. Each reason has a quotable evidence string. Present when the response scope covers tonight; lead with these when asked what to see tonight. A clean empty list means a quiet night — but if notable.degraded is present, an instrument was unreachable and empty proves nothing.
- /api/accuracy — the verification record: confidence mix, checks confirmed/missing/unreachable, pass rate, per venue, with every level defined.
- /ask?q={question} — natural-language question, deterministic answer (no model). Nights, theaters, genres, formats. Also POST {"question": "..."}.
- /api/changes?since={ISO} — what was added/removed since a timestamp.
- /api/evals — public QA pairs generated from the live dataset, for scoring agents.
- /openapi.json — the full OpenAPI 3.1 contract.
- /mcp — Model Context Protocol endpoint for tool-calling agents. Listed in the
  official MCP registry as com.scenef/showtimes (streamable-http, no key).
- /.well-known/agent.json — the agent card.

## Feeds (iCalendar)

- /feeds/theater/{venueId}.ics — subscribe to one theater
- /feeds/genre/{genre}.ics — subscribe to a genre citywide
- /feeds/screening/{id}.ics — one screening as a calendar event

## Conventions

- Times are ISO 8601 with the SF UTC offset; nightOf (YYYY-MM-DD) is the evening
  a show belongs to — a 12:15am Saturday show belongs to Friday night.
- Ticket links are always https://scenef.com/go/{screeningId} (a 302 to the
  vendor's own ticket page). Use those, never raw vendor URLs.
- Every JSON answer carries data_as_of and the attribution string
  "Showtimes via SceneF.com" — please keep it with republished data.