{
  "openapi": "3.1.0",
  "info": {
    "title": "Foul Domain API",
    "version": "2.0.0",
    "description": "Phish concert analytics API. Query 36,000+ analyzed tracks with performance scores, jam ratings, and audio data."
  },
  "servers": [
    { "url": "https://fouldomain.com" }
  ],
  "paths": {
    "/api/public/song": {
      "get": {
        "operationId": "searchSongs",
        "summary": "Search for Phish songs by name",
        "description": "Returns matching songs with play counts, debut/last played dates, gap, and audio analysis stats.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Song name to search for (partial match)"
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching songs with stats"
          }
        }
      }
    },
    "/api/public/best-versions": {
      "get": {
        "operationId": "getBestVersions",
        "summary": "Get top-rated versions of a Phish song",
        "description": "Returns the highest-scoring performances of a song, ranked by performance score. Filter by year, year range, venue, or state.",
        "parameters": [
          {
            "name": "song",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Song title (partial match, e.g. 'Tweezer', 'Ghost')"
          },
          {
            "name": "year",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Filter to a single year (e.g. 1997)"
          },
          {
            "name": "startYear",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Start of year range (e.g. 1997)"
          },
          {
            "name": "endYear",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "End of year range (e.g. 1999)"
          },
          {
            "name": "venue",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by venue name (partial match, e.g. 'MSG', 'Garden')"
          },
          {
            "name": "state",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by state (e.g. 'NY', 'Colorado')"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 10, "maximum": 25 },
            "description": "Number of results to return"
          }
        ],
        "responses": {
          "200": {
            "description": "List of top-rated versions with scores, duration, BPM, groove, likes, and tags"
          }
        }
      }
    },
    "/api/public/show": {
      "get": {
        "operationId": "getShow",
        "summary": "Get details of a specific Phish show",
        "description": "Returns full show details including venue, tour, show score, Phish.net rating, and complete setlist with per-song scores and durations.",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": true,
            "schema": { "type": "string" },
            "description": "Show date in YYYY-MM-DD format"
          }
        ],
        "responses": {
          "200": {
            "description": "Show details with setlist"
          }
        }
      }
    },
    "/api/public/top-shows": {
      "get": {
        "operationId": "getTopShows",
        "summary": "Get highest-rated Phish shows",
        "description": "Returns top shows ranked by show score. Filter by year, year range, tour name, venue, or state.",
        "parameters": [
          {
            "name": "year",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Filter to a single year"
          },
          {
            "name": "startYear",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Start of year range"
          },
          {
            "name": "endYear",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "End of year range"
          },
          {
            "name": "tour",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by tour name (partial match)"
          },
          {
            "name": "venue",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by venue name (partial match)"
          },
          {
            "name": "state",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by state"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 10, "maximum": 25 },
            "description": "Number of results"
          }
        ],
        "responses": {
          "200": {
            "description": "List of top-rated shows with scores and ratings"
          }
        }
      }
    },
    "/api/public/find-jams": {
      "get": {
        "operationId": "findJams",
        "summary": "Search for Phish jams by style, song, year, venue, and audio characteristics",
        "description": "Find jams matching specific criteria. Filter by song name, jam tags (Dark, Funk, Bliss, Type II, etc.), year/range, venue, state, BPM, duration, groove. Sort by score, duration, or groove.",
        "parameters": [
          {
            "name": "song",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by song name (e.g. 'Tweezer')"
          },
          {
            "name": "tag",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Comma-separated jam tags: Type I, Type II, Funk, Bliss, Dark, Ambient, Rock, Peak, Build, Experimental"
          },
          {
            "name": "year",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Filter to a single year"
          },
          {
            "name": "startYear",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Start of year range"
          },
          {
            "name": "endYear",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "End of year range"
          },
          {
            "name": "venue",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by venue name (partial match)"
          },
          {
            "name": "state",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by state"
          },
          {
            "name": "minBpm",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Minimum BPM"
          },
          {
            "name": "maxBpm",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Maximum BPM"
          },
          {
            "name": "minDuration",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Minimum duration in minutes"
          },
          {
            "name": "minGroove",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Minimum groove score (0-100)"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": { "type": "string", "enum": ["score", "duration", "groove", "bpm"] },
            "description": "Sort results by field (default: score)"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 10, "maximum": 25 },
            "description": "Number of results"
          }
        ],
        "responses": {
          "200": {
            "description": "List of jams with scores, duration, BPM, groove, and tags"
          }
        }
      }
    },
    "/api/public/bustouts": {
      "get": {
        "operationId": "getBustouts",
        "summary": "Find songs with long gaps between performances",
        "description": "Without a year, returns current bustout candidates (songs not played in many shows). With a year, returns bustouts that occurred that year.",
        "parameters": [
          {
            "name": "minGap",
            "in": "query",
            "schema": { "type": "integer", "default": 20 },
            "description": "Minimum show gap to qualify as a bustout (default 20)"
          },
          {
            "name": "year",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Find bustouts that occurred in this year"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 25, "maximum": 50 },
            "description": "Number of results"
          }
        ],
        "responses": {
          "200": {
            "description": "List of songs with gap counts"
          }
        }
      }
    },
    "/api/public/shows-by-venue": {
      "get": {
        "operationId": "getShowsByVenue",
        "summary": "Find Phish shows at a specific venue, city, or state",
        "description": "Search for shows by venue name, city, or state. Returns shows sorted by date (most recent first) with scores and ratings.",
        "parameters": [
          {
            "name": "venue",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Venue name (partial match, e.g. 'Madison Square', 'Red Rocks')"
          },
          {
            "name": "city",
            "in": "query",
            "schema": { "type": "string" },
            "description": "City name (partial match)"
          },
          {
            "name": "state",
            "in": "query",
            "schema": { "type": "string" },
            "description": "State (e.g. 'CO', 'New York')"
          },
          {
            "name": "year",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Filter to a specific year"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 25, "maximum": 50 },
            "description": "Number of results"
          }
        ],
        "responses": {
          "200": {
            "description": "List of shows with dates, venues, scores, and ratings"
          }
        }
      }
    }
  }
}