Trust & stability

Audience & versioning

The family-safe default, and what v1 promises not to break.

View as Markdown

Audience

The API defaults to family-safe. Every event, class, camp, and place carries an audience field — kids, families, teens, adults, or all_ages. Adult-only content is excluded by default on every list endpoint; a detail read (GET /v1/events/{id}) always returns the item regardless of audience, so a permalink resolves either way.

cURL

GET /v1/philadelphia/events                          # adults-only rows excluded
GET /v1/philadelphia/events?audience=adults           # only adults-only rows
GET /v1/philadelphia/events?audience=all              # every audience
GET /v1/philadelphia/events?audience=teens,families   # a specific combination

Versioning & stability

The version lives in the path (/v1/...) only — no version header, no Accept override. v1 is frozen: every path, parameter, and response field named in the endpoint reference is a promise. New optional parameters, new response fields, and new error.code values are additive and may appear at any time — parse permissively.

x-stability: beta or experimental on an operation or parameter marks the exceptions to the freeze; everything else unmarked is stable.

Timestamp fields

Suffix	Meaning
`*_at`	UTC, RFC 3339 (`starts_at`, `created_at`)
`*_local`	Naive local wall-clock time, no offset, read against the object's own `timezone`
`*_on`	A calendar date

What to do

Pass audience=all (or name a specific audience) explicitly when your use case needs it — don't rely on the default staying family-safe forever without checking.
Don't build on a beta or experimental surface without watching for change notices; unmarked surface is safe to depend on.
Format *_at fields as UTC in your own storage, and convert to *_local's timezone only for display.