# MusicFestivals.ai API
> A public REST API for discovering music festivals, artists, and genres.

Base URL: /api/v1
All responses use the envelope: { data, meta: { count, filters? } }

## Endpoints

### GET /api/v1/festivals
List and filter festivals. All filters are AND-combined.

Query parameters:
- genre: Comma-separated genre names (e.g. "Rock,Electronic")
- month: Comma-separated months 1-12 (e.g. "6,7,8" for summer)
- priceTier: Comma-separated price tiers (e.g. "budget,mid,premium")
- artist: Search string to match artist names (case-insensitive)
- near: Latitude,longitude for proximity search (e.g. "40.7128,-74.0060")
- radius: Radius in km for geo filter (default: 500)

Returns: Array of festival summaries with id, name, slug, locationCity, locationRegion, venueName, latitude, longitude, startDate, endDate, priceTier, startingPrice, heroImageUrl, genres[].

Example:
  curl "/api/v1/festivals?genre=Electronic&month=6,7"
  curl "/api/v1/festivals?near=40.7128,-74.0060&radius=200"
  curl "/api/v1/festivals?artist=DJ&priceTier=budget,mid"

### GET /api/v1/festivals/{slug}
Get full detail for a single festival by its URL slug.

Returns: Complete festival object with genres[], amenities[] (with icon), and artists[] (with isHeadliner, headlinerTag, genres[]).

Example:
  curl "/api/v1/festivals/coachella-2026"

### GET /api/v1/artists
List artists, optionally filtered.

Query parameters:
- genre: Filter by genre name (case-insensitive exact match)
- festival: Filter by festival slug

Returns: Array of artists with id, name, photoUrl, genres[].

Example:
  curl "/api/v1/artists?genre=Electronic"
  curl "/api/v1/artists?festival=coachella-2026"

### GET /api/v1/genres
List all genres with festival counts.

Returns: Array of genres with id, name, festivalCount.

Example:
  curl "/api/v1/genres"

## OpenAPI Spec
Machine-readable OpenAPI 3.1 spec available at: /api/v1/openapi.json