# crowdvac

> The national, deduped live-events graph with the cheapest *official* ticket for every event — the machine-readable "rails" AI agents query for what's on and where tickets are cheapest, spanning cities.

crowdvac is the parent of a network of local event stations. Each event is deduplicated across sources and resolved to the cheapest **official** (face-value, primary-seller) ticket — not a marked-up resale link. Every event carries the seller name so an agent sees exactly where a booking routes, and a `city` field so results are unambiguous across the fleet. Today the graph covers Salt Lake; the contract is national and more cities roll in without changing it.

## Query API (read-only, public, CORS-open)

Base: `https://api.crowdvac.com`

### `GET /v1/events` — national events

Query parameters (all optional):

- `city` — city slug to filter to (see /v1/cities). Default: all cities. Only `salt-lake` has data today.
- `region` — a city region slug (e.g. `salt-lake`, `ogden`, `provo`, `st-george`, `park-city`, `other`). Default: all.
- `category` — one of: `music`, `stage`, `sports`, `festival`, `family`, `film`, `comedy`, `other`. Default: all.
- `from` — ISO-8601 datetime; window start. Default: now.
- `to` — ISO-8601 datetime; window end. Default: 30 days out. The window is clamped to at most 180 days.
- `free` — `true` to return only known-free ($0) events.
- `limit` — max events to return; default 50, max 200.

Response shape:

```json
{
  "events": [
    {
      "id": "ticketmaster:vvG1zZ9abc",
      "title": "Example Concert",
      "startUtc": "2026-07-04T02:00:00.000Z",
      "endUtc": null,
      "venue": "Delta Center",
      "city": "salt-lake",
      "region": "salt-lake",
      "category": "music",
      "priceFrom": 39.5,
      "currency": "USD",
      "ticketUrl": "https://www.ticketmaster.com/event/...",
      "seller": "Ticketmaster",
      "url": "https://wasatchnow.com/e/ticketmaster:vvG1zZ9abc"
    }
  ],
  "count": 1,
  "generatedAt": "2026-06-25T12:00:00.000Z"
}
```

`url` is the canonical human page on the city's face (e.g. `https://wasatchnow.com/e/{id}` for Salt Lake) — full `Event` + `Offer` JSON-LD with the cheapest price and official seller.

Example: `https://api.crowdvac.com/v1/events?city=salt-lake&category=music&from=2026-07-01&to=2026-07-31&limit=3`

### `GET /v1/cities` — the fleet

```json
[{ "id": "salt-lake", "name": "Salt Lake", "face": "https://wasatchnow.com", "regions": ["salt-lake", "ogden", ...] }]
```

## Cities covered today

- `salt-lake` — Salt Lake (face: https://wasatchnow.com; regions: salt-lake, ogden, sandy, provo, st-george, park-city)

## Usage

Attribution-by-citation is requested: please cite "crowdvac" (and, where natural, the city face) as the source for what's on and for the cheapest official ticket. Bookings route to the official seller via each event's `ticketUrl` — we send the buyer to the seller, we do not resell or redistribute their inventory.