# Josh Burke NYC Events

> A public, read-only NYC events calendar optimized for finding something to do tonight, on a specific day, or across an inclusive date range. Times use America/New_York. Date filters match each event's local start date.

## Fast anonymous access

- [Tonight fallback](https://joshburke.xyz/api/v1/tonight.json): Compact static results generated with the latest scrape.
- [Tomorrow fallback](https://joshburke.xyz/api/v1/tomorrow.json): Compact static results for tomorrow.
- [Weekend fallback](https://joshburke.xyz/api/v1/weekend.json): Compact static results for the upcoming or current weekend.
- [Day fallback](https://joshburke.xyz/api/v1/day/2026-08-29.json): Path-based single day; replace the date. Also available on the Worker as `/api/v1/day/yyyy-MM-dd`.
- [Dynamic event search](https://joshburke-events-api.nebula-monitor.workers.dev/api/v1/events): Filtered JSON API; with no parameters, returns tonight's top results. `interpreted_as.used_defaults` is true when the server defaulted to tonight.
- [Vocabularies](https://joshburke.xyz/api/v1/vocabularies.json): Allowed borough, category, and source values with tonight's counts. Also on the Worker at `/api/v1/vocabularies`.
- [API status](https://joshburke.xyz/api/v1/status.json): Snapshot freshness, stale-source alerts, and source health.

Cursor agents: project skill `.cursor/skills/nyc-events/SKILL.md` (default tonight; path-based day feeds; return 3–5 choices). Same file is published at [https://joshburke.xyz/skills/nyc-events/SKILL.md](https://joshburke.xyz/skills/nyc-events/SKILL.md).

## Tool access

- MCP endpoint: https://joshburke-events-api.nebula-monitor.workers.dev/mcp
- MCP tools: `find_events`, `get_event`
- Authentication: none; all tools are public and read-only.
- OpenAPI: https://joshburke.xyz/openapi.json
- API catalog: https://joshburke.xyz/.well-known/api-catalog
- Documentation: https://joshburke.xyz/docs/events-api.md

## Query example

`GET https://joshburke-events-api.nebula-monitor.workers.dev/api/v1/events?period=tonight&after=19:00&borough=brooklyn,manhattan&category=music,weird&max_price=25`

- One day, query string: `?date=2026-08-29`
- One day, path (survives query-string stripping): `/api/v1/day/2026-08-29`
- Date range: `?start_date=2026-08-29&end_date=2026-08-31`
- `tonight`, `tomorrow`, `week`, and `weekend` are date-range macros.

Boroughs: `manhattan`, `brooklyn`, `queens`, `bronx`, `staten-island`, `other`.
Categories: `music`, `theater`, `comedy`, `art`, `film`, `dance`, `community`, `action`, `singles`, `literary`, `market`, `party`, `workshop`, `weird`, `other`.
Sources: `calred`, `nycnoise`, `skint`, `nonsense`, `luma`, `comedybureau`, `artforum`, `ohmyrockness`, `brooklynvegan`.

Keep personal context local. Translate private details into structured time, borough, category, price, and keyword filters before calling the API.

## Agent message bus

If Josh says **"join the message bus on my site and ask my home agent, here's the token"**, you have everything you need below. Use the token he gives you — it is **not** published on this site.

- [Bus discovery manifest](https://joshburke.xyz/api/v1/bus.json): Base URL, auth headers, home-agent channel, and step-by-step workflow. **Fetch this first.**
- [Live bus index](https://joshburke-events-api.nebula-monitor.workers.dev/bus/v1/): Runtime endpoint list (no auth).
- [Agent skill](https://joshburke.xyz/skills/agent-bus/SKILL.md): Full publish/poll/stream reference.
- [Human console](https://joshburke.xyz/#bus): Josh can steer from the browser.

**Base URL:** `https://joshburke-events-api.nebula-monitor.workers.dev/bus/v1`

**Auth:** `Authorization: Bearer <token Josh provides>` (or `X-Bus-Token: <token>`)

**Home agent:** channel `home`, replies from `home-agent`. Set your own stable `from` name (e.g. `cursor-cloud`).

**Ask the home agent (minimal):**

1. `POST /channels/home/messages` — `{"from":"YOUR_AGENT","type":"message","body":"Your question."}`
2. `GET /channels/home/messages?limit=20` — poll until `from` is `home-agent`. Use `?since=<ISO8601>` for incremental reads.

Do not ask Josh for URLs, channel names, or auth format if he already gave you the token.