Developers

The TruckeeVibes events API

A free, read-only JSON list of events around Truckee and North Lake Tahoe. No key, no sign-up. Please show the credit line with the data.

Endpoint

GET https://truckeevibes.com/api/v1/events

curl 'https://truckeevibes.com/api/v1/events?scope=vibes&area=truckee&limit=20'
curl 'https://truckeevibes.com/api/v1/events?scope=lights&season=christmas&year=2026'

Parameters

Name	Values	Meaning
`scope`	vibes (default) or lights	vibes = the TruckeeVibes list. lights = the events shown on Truckee Lights and Truckee Frights for one season.
`season`	halloween or christmas	Required with scope=lights; not allowed otherwise.
`year`	four digits, 2025 to 2100	The season’s December year. Required with scope=lights.
`from`	YYYY-MM-DD	First local day (Pacific). Earlier than today means now: ended events never come back.
`to`	YYYY-MM-DD	Last local day (Pacific), inclusive. The window is at most 120 days.
`area`	comma list, up to 10	Area slugs, e.g. truckee,donner_lake. scope=vibes only.
`category`	comma list, up to 10	Category slugs, e.g. music,outdoors. scope=vibes only.
`limit`	1 to 500	Events per page. Default 200 (vibes) or 500 (lights).
`cursor`	opaque	The nextCursor of the previous page.

Unknown or repeated parameters are refused. Events are ordered by start time, then id; follow nextCursor until it is null.

Response

One JSON object. The JSON Schema is the contract; new fields may be added within v1, nothing is removed or renamed.

Field	Type	Meaning
`version`	1	API major version.
`scope`	"vibes" \| "lights"	vibes = the TruckeeVibes list; lights = the events shown on Truckee Lights / Truckee Frights for one season.
`season`	"halloween" \| "christmas" \| null	The season (scope=lights), else null.
`year`	integer \| null	The season's December year (scope=lights), else null.
`dataAt`	string (date-time)	When the database produced this page (UTC).
`stale`	boolean	Always false in v1: there is no stale fallback (an outage is a 503). Kept so clients can keep checking it.
`pageComplete`	boolean	true when this is the last page (nextCursor is null).
`mirror`	object	Freshness of the Truckee Lights mirror (scope=lights). Always state none for scope=vibes.
`region`	object	The region the list covers.
`count`	integer	Events on this page.
`nextCursor`	string \| null	Pass as cursor= for the next page; null on the last page.
`attribution`	object	Credit line to show with the data.
`events`	array of event	Events ordered by start time, then id.

Event fields

Field	Type	Meaning
`id`	string (uuid)	Stable event id (a Truckee Lights id for origin=lights).
`origin`	"lights" \| "vibes"	Where the event comes from.
`formerIds`	array of string (uuid)	Ids of events merged into this one (up to 5 hops).
`pageUrl`	string \| null	The event's TruckeeVibes page, when it has one.
`title`	string
`description`	string \| null	Organizer text; only on origin=lights rows.
`summary`	string \| null	Our one-line summary; only on origin=vibes rows.
`startsAt`	string (date-time)	Start (UTC).
`endsAt`	string \| null (date-time)	End (UTC), when known. All-day events end at local midnight after the last day.
`allDay`	boolean
`startDate`	string \| null (date)	First local day of an all-day event.
`endDate`	string \| null (date)	Day after the last local day of an all-day event (exclusive).
`timeKnown`	boolean	false when the source gave a date but no time.
`venue`	string \| null
`address`	string \| null
`town`	string \| null
`lat`	number \| null
`lng`	number \| null
`categories`	array of string	Category slugs.
`age`	"all_ages" \| "family" \| "18_plus" \| "21_plus" \| "unknown"
`adultsOnly`	boolean	21 and over.
`url`	string \| null	The organizer's page for the event.
`ticketUrl`	string \| null

Errors

400 {"error":"bad_param","param":"<name>"}: a parameter is unknown, repeated or out of range.
405: only GET, HEAD and OPTIONS are allowed.
503 {"error":"unavailable"} with retry-after: 60: the database is unreachable. There is no stale fallback; try again in a minute.

Caching

Fresh responses: cache-control: public, max-age=60, s-maxage=300. A new or removed event can take up to 5 minutes to show.
No stale fallback: if the database is down you get a 503, never an older copy of the list, so a removed event never comes back. stale is always false.
For scope=lights, mirror.state says whether the Truckee Lights list was last read cleanly (confirmed) or a large removal is waiting for review (held).

CORS

Browsers on truckeelights.com, truckeefrights.com and truckeevibes.com get access-control-allow-origin. This is etiquette, not access control: the data is public, and server-side calls work from anywhere. Please cache responses and keep request rates modest.

Versioning

Within /api/v1 changes are additive only. A breaking change ships as /api/v2, and v1 keeps working.

Embed

const res = await fetch('https://truckeevibes.com/api/v1/events?scope=vibes&limit=20');
const { events, attribution } = await res.json();
// show attribution.name linked to attribution.url with the list