{"openapi":"3.1.0","info":{"title":"SceneF","version":"0.1.0","description":"Every movie showtime in San Francisco — chains, indies, repertory — verified nightly against each theater's own calendar.\n\nURL GRAMMAR (human pages, also negotiable to JSON/markdown via the Accept header):\n/ (tonight) · /week · /film/{slug} · /theater/{venueId} · /agents · /status · /methodology.\n\nBRING-YOUR-OWN-PROFILE — any listing page or API slice accepts preference params, never stored server-side:\nlikes=<genre,genre> · no=<genre|matinee,...> · window=matinee|early|evening|late · home=<venueId,venueId> · formats=<35mm,70mm,imax,...> · discounts=only.\nRanking is pure preference-scoring: nothing is hidden and nothing is pay-ranked.\n\nTICKETS: every ticket link is https://scenef.com/go/{screeningId}, a 302 to the vendor's own page. Link those, never raw vendor URLs.\n\nACCURACY is computed and published, never asserted. Every screening carries confidence, source_tier, sources, and verified_at; the running record of our own verification checks — including the ones that failed and the ones that could not run — is at /api/accuracy. Checks blocked by a bot wall are graded unreachable and excluded from the pass rate; the pass rate is null, not 100%, when nothing gradeable has run. Chain showtimes are licensed from an aggregator rather than read first-hand (source_tier licensed-feed).\n\nNOTABLE: listings responses whose scope covers tonight (full feed, when=tonight, when=week, night=today; never venue/film slices) carry notable.items — scarcity FACTS about tonight, citywide, never taste. The why vocabulary is closed: 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 (a posted day-bound price), live-event (live score, Q&A, sing-along). Each reason carries an evidence string — quote it verbatim. When a user asks what to see tonight, lead with these facts, then taste. A clean empty list means tonight holds no such fact; if notable.degraded is present, an instrument was unreachable and empty is NOT proof of a quiet night.\nPlease keep the attribution string with any republished data."},"servers":[{"url":"https://scenef.com"}],"paths":{"/api/listings":{"get":{"operationId":"getListings","summary":"The canonical open feed: venues, films, screenings. Full dataset by default; slice with query params.","description":"LLM callers: ALWAYS slice (when=tonight|week or night=YYYY-MM-DD) AND pass compact=1 — the bare feed tops 1MB and tool harnesses truncate it. notable.items lists tonight's scarcity facts with quotable evidence; lead with them when asked what to see tonight.","parameters":[{"name":"venue","in":"query","required":false,"schema":{"type":"string"},"description":"Venue id, e.g. roxie, balboa, alamo-new-mission"},{"name":"night","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"One evening (nightOf), YYYY-MM-DD"},{"name":"film","in":"query","required":false,"schema":{"type":"string"},"description":"Film slug, e.g. the-matrix-1999"},{"name":"when","in":"query","required":false,"schema":{"type":"string","enum":["tonight","week"]}},{"name":"compact","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Agent diet: every screening kept, each record stripped to essentials (film facts, showtime, ticketUrl, confidence). LLM tool callers should always send compact=1."}],"responses":{"200":{"description":"The feed. ETagged; send If-None-Match for a 304.","content":{"application/json":{"schema":{"type":"object","properties":{"generated":{"type":"string"},"data_as_of":{"type":"string","description":"ISO timestamp of the dataset build this answer came from"},"attribution":{"type":"string","const":"Showtimes via SceneF.com"},"docs":{"type":"string"},"counts":{"type":"object","properties":{"films":{"type":"integer"},"screenings":{"type":"integer"},"venues":{"type":"integer"},"tonight":{"type":"integer"}}},"accuracy":{"type":"string","description":"URL of the accuracy record for this data"},"notable":{"type":"object","description":"Scarcity facts about tonight, citywide, each with quotable evidence — never taste or ratings. Present only when the response scope covers tonight. Lead with these when asked what to see tonight. A clean empty items[] means tonight holds no such fact; if degraded[] is present an instrument was unreachable and empty proves nothing.","properties":{"note":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"screeningId":{"type":"string"},"title":{"type":"string"},"filmSlug":{"type":"string"},"venue":{"type":"string"},"startsAt":{"type":"string"},"nightOf":{"type":"string"},"time":{"type":"string"},"ticketUrl":{"type":"string"},"reasons":{"type":"array","description":"Primary reason first.","items":{"type":"object","properties":{"why":{"type":"string","enum":["selling-fast","last-night","only-print","cheap-night","live-event"]},"evidence":{"type":"string","description":"The receipt behind the claim, e.g. '61 of 82 seats taken as of 6:45 PM'. Quote it verbatim."}}}}}}},"degraded":{"type":"array","items":{"type":"string"}},"degraded_note":{"type":"string"}}},"venues":{"type":"array","items":{"type":"object"}},"films":{"type":"array","items":{"type":"object"}},"screenings":{"type":"array","items":{"type":"object","description":"One showtime. ticketUrl is always https://scenef.com/go/{id}. The accuracy fields are stamped by the pipeline, never by an adapter.","properties":{"id":{"type":"string"},"filmKey":{"type":"string"},"venueId":{"type":"string"},"startsAt":{"type":"string","description":"ISO 8601 with the theater's UTC offset"},"nightOf":{"type":"string","description":"YYYY-MM-DD — the evening this show belongs to"},"tags":{"type":"array","items":{"type":"string"}},"ticketUrl":{"type":"string"},"priceNote":{"type":"string"},"provenance":{"type":"object","description":"Raw provenance record: sourceTier, source, fetchedAt, lastVerifiedAt, confidence, sources, note"},"confidence":{"type":["string","null"],"enum":["venue-published","corroborated","single-source","disputed",null],"description":"How well this showtime is known. Defined in full at /api/accuracy."},"source_tier":{"type":"string","enum":["venue-api","public-feed","verified-scrape","licensed-feed"],"description":"Where it came from. licensed-feed is bought from an aggregator, not read from the venue."},"sources":{"type":"array","items":{"type":"string"},"description":"Every source that reported this exact showtime, e.g. [\"veezi:sessions\"]"},"verified_at":{"type":"string","description":"ISO time this listing last passed a check (provenance.lastVerifiedAt)"},"note":{"type":"string","description":"Present only when sources disagree — what the disagreement was"}}}}}}}}},"304":{"description":"Not modified (If-None-Match matched)"}}}},"/api/accuracy":{"get":{"operationId":"getAccuracy","summary":"The accuracy record: how well the board is known and what our own verification runs found, failures included. Computed on every call, never asserted.","responses":{"200":{"description":"Site-wide and per-venue accuracy. Every level used is defined inline under `method`.","content":{"application/json":{"schema":{"type":"object","properties":{"data_as_of":{"type":"string","description":"ISO timestamp of the dataset build this answer came from"},"attribution":{"type":"string","const":"Showtimes via SceneF.com"},"site":{"type":"object","properties":{"checks":{"type":"integer","description":"Verification checks in the window"},"confirmed":{"type":"integer","description":"The check ran and agreed with what we publish"},"missing":{"type":"integer","description":"The check ran and did not agree"},"unreachable":{"type":"integer","description":"The check could not run (bot wall, client-rendered page, network failure). Excluded from pass_rate."},"pass_rate":{"type":["number","null"],"description":"confirmed / (confirmed + missing). null when nothing gradeable ran — never 1.0 out of an empty denominator."},"window_days":{"type":"integer","description":"Reporting window these counts cover"},"pass_rate_basis":{"type":"string","description":"The denominator, stated in words"},"computed_from":{"type":"string","description":"Which artifact produced these numbers: the rolling check ledger or the note log"},"first_check_at":{"type":["string","null"],"description":"When the record opens — published with the rate so a high number over a young record cannot pose as a long one"},"last_check_at":{"type":["string","null"]},"screenings":{"type":"integer","description":"Screenings currently published"},"confidence_mix":{"type":"object","description":"Count of published screenings at each confidence level","additionalProperties":{"type":"integer"}}}},"venues":{"type":"array","items":{"type":"object","properties":{"venue_id":{"type":"string"},"name":{"type":"string"},"source_tier":{"type":["string","null"],"description":"null when this venue publishes no showtimes here (link-out only)"},"screenings":{"type":"integer"},"confidence_mix":{"type":"object","additionalProperties":{"type":"integer"}},"last_verified_at":{"type":["string","null"]},"note":{"type":"string","description":"Source-health note when the venue is not publishing showtimes"},"checks":{"type":"integer","description":"Verification checks in the window"},"confirmed":{"type":"integer","description":"The check ran and agreed with what we publish"},"missing":{"type":"integer","description":"The check ran and did not agree"},"unreachable":{"type":"integer","description":"The check could not run (bot wall, client-rendered page, network failure). Excluded from pass_rate."},"pass_rate":{"type":["number","null"],"description":"confirmed / (confirmed + missing). null when nothing gradeable ran — never 1.0 out of an empty denominator."}}}},"method":{"type":"object","properties":{"rings":{"type":"array","items":{"type":"string"},"description":"The three verification rings, one line each"},"confidence_levels":{"type":"object","additionalProperties":{"type":"string"}},"source_tiers":{"type":"object","additionalProperties":{"type":"string"}},"check_grades":{"type":"object","additionalProperties":{"type":"string"}}}},"docs":{"type":"string"}}}}}}}}},"/api/changes":{"get":{"operationId":"getChanges","summary":"Diff the current dataset against the newest snapshot at or before `since`.","parameters":[{"name":"since","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"ISO timestamp; defaults to the current build (empty diff)"}],"responses":{"200":{"description":"Added/removed screenings and newly listed films","content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string"},"baseline_generated":{"type":["string","null"]},"current_generated":{"type":"string"},"added":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"film":{"type":"string"},"venue":{"type":"string"},"startsAt":{"type":"string","description":"ISO 8601 with SF UTC offset"},"night":{"type":"string","description":"nightOf, YYYY-MM-DD; shows before 4am belong to the previous evening"}}}},"removed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"film":{"type":"string"},"venue":{"type":"string"},"startsAt":{"type":"string","description":"ISO 8601 with SF UTC offset"},"night":{"type":"string","description":"nightOf, YYYY-MM-DD; shows before 4am belong to the previous evening"}}}},"films_added":{"type":"array","items":{"type":"string"}},"data_as_of":{"type":"string","description":"ISO timestamp of the dataset build this answer came from"},"attribution":{"type":"string","const":"Showtimes via SceneF.com"}}}}}}}}},"/ask":{"get":{"operationId":"ask","summary":"Natural-language showtime question, deterministic answer (no model). Understands nights, theaters, genres, formats.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"example":"what horror is playing in SF tonight"}],"responses":{"200":{"description":"Plain-English answer plus structured results","content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string","description":"Plain English, <=120 words"},"results":{"type":"array","maxItems":20,"items":{"type":"object","properties":{"film":{"type":"string"},"venue":{"type":"string"},"startsAt":{"type":"string"},"night":{"type":"string"},"scenef_url":{"type":"string"},"ticket_url":{"type":"string","description":"https://scenef.com/go/{screeningId}"}}}},"interpreted":{"type":"object","properties":{"when":{"type":"string"},"nights":{"type":"array","items":{"type":"string"}},"venue":{"type":["string","null"]},"genres":{"type":"array","items":{"type":"string"}},"formats":{"type":"array","items":{"type":"string"}}}},"data_as_of":{"type":"string","description":"ISO timestamp of the dataset build this answer came from"},"attribution":{"type":"string","const":"Showtimes via SceneF.com"}}}}}}}},"post":{"operationId":"askPost","summary":"Same as GET /ask, question in the body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"properties":{"question":{"type":"string"}}}}}},"responses":{"200":{"description":"Same shape as GET /ask"}}}},"/go/{id}":{"get":{"operationId":"goToTickets","summary":"The ticket door: 302 to the vendor's own ticket page for a screening.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Screening id from any feed"}],"responses":{"302":{"description":"Redirect to the ticket page (venue website as fallback; scenef.com/?missing=1 for unknown ids)"}}}},"/feeds/theater/{venueId}.ics":{"get":{"operationId":"theaterCalendar","summary":"iCalendar feed of one theater's screenings — subscribe in any calendar app.","parameters":[{"name":"venueId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/calendar","content":{"text/calendar":{"schema":{"type":"string"}}}}}}},"/feeds/genre/{genre}.ics":{"get":{"operationId":"genreCalendar","summary":"iCalendar feed of every SF screening in a genre.","parameters":[{"name":"genre","in":"path","required":true,"schema":{"type":"string"},"example":"horror"}],"responses":{"200":{"description":"text/calendar","content":{"text/calendar":{"schema":{"type":"string"}}}}}}},"/feeds/screening/{id}.ics":{"get":{"operationId":"screeningCalendarEvent","summary":"A single screening as a calendar event.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/calendar","content":{"text/calendar":{"schema":{"type":"string"}}}}}}},"/api/evals":{"get":{"operationId":"getEvals","summary":"Public eval set: QA pairs generated from the live dataset, refreshed with every build.","responses":{"200":{"description":"QA pairs with expected substrings and source URLs","content":{"application/json":{"schema":{"type":"object","properties":{"pairs":{"type":"array","items":{"type":"object","properties":{"q":{"type":"string"},"expected_contains":{"type":"array","items":{"type":"string"}},"source_url":{"type":"string"}}}},"note":{"type":"string"},"data_as_of":{"type":"string","description":"ISO timestamp of the dataset build this answer came from"},"attribution":{"type":"string","const":"Showtimes via SceneF.com"}}}}}}}}}}}