# Audience & versioning

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

Source: https://api.tailend.dev/docs/audience-and-versioning

## 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.

```bash
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.