{"info":{"title":"Phish.in API v2","description":"A RESTful API for accessing data and content on [Phish.in](https://phish.in), an open source archive of live Phish audience recordings. This API returns the complete catalog of known Phish setlists, including shows without audience recordings (marked with audio_status: 'missing'). See [GitHub](https://github.com/jcraigk/phishin) for development and issue tracking. Access is provided free of charge and without warranty. Please be nice.\n\n**MCP Server:** An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server is also available at `POST https://phish.in/mcp` for AI assistant integration.","version":"0.0.1"},"swagger":"2.0","produces":["application/json"],"host":"phish.in","basePath":"/api/v2","tags":[{"name":"announcements","description":"Announcements about new content and site updates"},{"name":"auth","description":"User authentication including registration, login, and password reset"},{"name":"likes","description":"User likes (upvotes) on shows, tracks, and playlists"},{"name":"playlists","description":"Playlists created by users"},{"name":"reports","description":"Reports about content"},{"name":"search","description":"Search across shows, songs, venues, tours, and tags"},{"name":"shows","description":"Live shows performed by Phish"},{"name":"songs","description":"Songs that Phish have played, including audio track URLs of live performances"},{"name":"tags","description":"Tags conveying metadata about shows and audio tracks"},{"name":"tours","description":"Tours that Phish have embarked on, including associated shows"},{"name":"tracks","description":"Tracks from live Phish shows, including links to audio if available"},{"name":"venues","description":"Venues that Phish have played at, including associated shows"},{"name":"years","description":"Years and eras during which Phish have performed live shows"}],"paths":{"/announcements":{"get":{"summary":"Fetch recent announcements","description":"Fetch the newest 100 announcements","produces":["application/json"],"responses":{"200":{"description":"Fetch recent announcements","schema":{"$ref":"#/definitions/ApiV2_Entities_Announcement"}}},"tags":["announcements"],"operationId":"getAnnouncements"}},"/auth/create_user":{"post":{"summary":"Create a new user","description":"Create a new user with the provided username, email, password, and password confirmation","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postAuthCreateUser","in":"body","required":true,"schema":{"$ref":"#/definitions/postAuthCreateUser"}}],"responses":{"201":{"description":"Create a new user and return a JWT for X-Auth-Token header","schema":{"$ref":"#/definitions/ApiV2_Entities_LoginResponse"}},"422":{"description":"Unprocessable Entity - User creation failed"},"409":{"description":"Conflict - Email already exists"}},"tags":["auth"],"operationId":"postAuthCreateUser"}},"/auth/login":{"post":{"summary":"User login via email and password","description":"Authenticate a user using their email and password and return a JWT for X-Auth-Token header","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postAuthLogin","in":"body","required":true,"schema":{"$ref":"#/definitions/postAuthLogin"}}],"responses":{"200":{"description":"User login via email and password","schema":{"$ref":"#/definitions/ApiV2_Entities_LoginResponse"}},"401":{"description":"Unauthorized - Invalid email or password"}},"tags":["auth"],"operationId":"postAuthLogin"}},"/auth/user":{"get":{"summary":"Fetch the currently logged in user","description":"Fetch the currently authenticated user","produces":["application/json"],"responses":{"200":{"description":"Fetch the currently logged in user","schema":{"$ref":"#/definitions/ApiV2_Entities_User"}},"401":{"description":"Unauthorized - Invalid JWT"}},"tags":["auth"],"operationId":"getAuthUser"}},"/auth/request_password_reset":{"post":{"summary":"Request password reset email","description":"Send a password reset email to the user if found","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postAuthRequestPasswordReset","in":"body","required":true,"schema":{"$ref":"#/definitions/postAuthRequestPasswordReset"}}],"responses":{"200":{"description":"Request password reset email","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["auth"],"operationId":"postAuthRequestPasswordReset"}},"/auth/reset_password":{"post":{"summary":"Reset a user's password via reset token","description":"Reset the user's password using a token received in the password reset email","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postAuthResetPassword","in":"body","required":true,"schema":{"$ref":"#/definitions/postAuthResetPassword"}}],"responses":{"201":{"description":"Reset a user's password via reset token","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"401":{"description":"Unauthorized - Invalid reset token"},"422":{"description":"Unprocessable Entity - Password reset failed"}},"tags":["auth"],"operationId":"postAuthResetPassword"}},"/auth/change_username/{username}":{"patch":{"summary":"Change username","description":"Change the current user's username, restricted to once per year","produces":["application/json"],"consumes":["application/json"],"parameters":[{"in":"path","name":"username","description":"New username","type":"string","required":true}],"responses":{"200":{"description":"Username changed successfully","schema":{"$ref":"#/definitions/ApiV2_Entities_User"}},"403":{"description":"Forbidden - Username can only be changed once per year"},"422":{"description":"Unprocessable Entity - Username change failed"}},"tags":["auth"],"operationId":"patchAuthChangeUsernameUsername"}},"/likes":{"post":{"summary":"Like or unlike a show, track, or playlist","description":"Creates a like for a show, track, or playlist. Restricted to authenticated users.","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postLikes","in":"body","required":true,"schema":{"$ref":"#/definitions/postLikes"}}],"responses":{"201":{"description":"Like or unlike a show, track, or playlist"},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"422":{"description":"Unprocessable Entity","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["likes"],"operationId":"postLikes"},"delete":{"summary":"Unlike a show, track, or playlist","description":"Removes a like for a show, track, or playlist. Restricted to authenticated users.","produces":["application/json"],"parameters":[{"in":"query","name":"likable_type","description":"Type of the likable object","type":"string","enum":["Show","Track","Playlist"],"required":true},{"in":"query","name":"likable_id","description":"ID of the likable object","type":"integer","format":"int32","required":true}],"responses":{"204":{"description":"Unlike a show, track, or playlist"},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"422":{"description":"Unprocessable Entity","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["likes"],"operationId":"deleteLikes"}},"/playlists":{"get":{"summary":"Fetch a list of playlists","description":"Fetch a filtered, sorted, paginated list of playlists","produces":["application/json"],"parameters":[{"in":"query","name":"page","description":"Page number for pagination (min: 1)","type":"integer","format":"int32","default":1,"required":false},{"in":"query","name":"per_page","description":"Number of items per page for pagination (min: 1, max: 1000)","type":"integer","format":"int32","default":10,"required":false},{"in":"query","name":"sort","description":"Sort by attribute and direction (e.g., 'likes_count:desc')","type":"string","default":"likes_count:desc","enum":["name:asc","name:desc","likes_count:asc","likes_count:desc","tracks_count:asc","tracks_count:desc","duration:asc","duration:desc","updated_at:asc","updated_at:desc"],"required":false},{"in":"query","name":"filter","description":"Filter by user ownership or user likes. Requires authentication.","type":"string","enum":["all","mine","liked"],"required":false}],"responses":{"200":{"description":"Fetch a list of playlists","schema":{"$ref":"#/definitions/ApiV2_Entities_Playlist"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["playlists"],"operationId":"getPlaylists"},"post":{"summary":"Create a new playlist","description":"Creates a new playlist for the authenticated user","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postPlaylists","in":"body","required":true,"schema":{"$ref":"#/definitions/postPlaylists"}}],"responses":{"201":{"description":"Create a new playlist","schema":{"$ref":"#/definitions/ApiV2_Entities_Playlist"}},"422":{"description":"Unprocessable Entity","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["playlists"],"operationId":"postPlaylists"}},"/playlists/{slug}":{"get":{"summary":"Fetch a playlist by slug","description":"Fetch a playlist by its slug, including all associated tracks","produces":["application/json"],"parameters":[{"in":"path","name":"slug","description":"Slug of the playlist","type":"string","required":true}],"responses":{"200":{"description":"Fetch a playlist by slug","schema":{"$ref":"#/definitions/ApiV2_Entities_Playlist"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["playlists"],"operationId":"getPlaylistsSlug"}},"/playlists/{id}":{"put":{"summary":"Update an existing playlist","description":"Updates an existing playlist for an authenticated user","produces":["application/json"],"consumes":["application/json"],"parameters":[{"in":"path","name":"id","description":"ID of the playlist","type":"integer","format":"int32","required":true},{"name":"putPlaylistsId","in":"body","required":true,"schema":{"$ref":"#/definitions/putPlaylistsId"}}],"responses":{"200":{"description":"Update an existing playlist","schema":{"$ref":"#/definitions/ApiV2_Entities_Playlist"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"422":{"description":"Unprocessable Entity","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["playlists"],"operationId":"putPlaylistsId"},"delete":{"summary":"Delete a playlist","description":"Deletes a playlist owned by the authenticated user","produces":["application/json"],"parameters":[{"in":"path","name":"id","description":"ID of the playlist","type":"integer","format":"int32","required":true}],"responses":{"204":{"description":"Delete a playlist"},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"403":{"description":"Forbidden","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["playlists"],"operationId":"deletePlaylistsId"}},"/reports/missing_content":{"get":{"summary":"Fetch a list of missing and incomplete content","description":"Returns a list of dates on which Phish is known to have played but for which there is partial or nonexistent audio in circulation","produces":["application/json"],"responses":{"200":{"description":"Fetch a list of missing and incomplete content","schema":{"$ref":"#/definitions/ApiV2_Entities_MissingContentReport"}}},"tags":["reports"],"operationId":"getReportsMissingContent"}},"/search/{term}":{"get":{"summary":"Search the database","description":"Perform a text based search across shows, tracks, songs, venues, and tags.","produces":["application/json"],"parameters":[{"in":"path","name":"term","description":"Search term (at least 3 characters long)","type":"string","required":true},{"in":"query","name":"audio_status","description":"Filter by audio status: 'any' (default), 'complete', 'partial', 'missing', 'complete_or_partial'","type":"string","default":"any","enum":["any","complete","partial","missing","complete_or_partial"],"required":false},{"in":"query","name":"scope","description":"Specifies the area of the site to search","type":"string","default":"all","enum":["all","playlists","shows","songs","tags","tours","tracks","venues"],"required":false}],"responses":{"200":{"description":"Search the database","schema":{"$ref":"#/definitions/ApiV2_Entities_SearchResults"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["search"],"operationId":"getSearchTerm"}},"/shows":{"get":{"summary":"Fetch a list of shows","description":"Fetch a filtered, sorted, paginated list of shows","produces":["application/json"],"parameters":[{"in":"query","name":"page","description":"Page number for pagination (min: 1)","type":"integer","format":"int32","default":1,"required":false},{"in":"query","name":"per_page","description":"Number of items per page for pagination (min: 1, max: 1000)","type":"integer","format":"int32","default":10,"required":false},{"in":"query","name":"lat","description":"Latitude for proximity search","type":"number","format":"float","required":false},{"in":"query","name":"lng","description":"Longitude for proximity search","type":"number","format":"float","required":false},{"in":"query","name":"distance","description":"Distance (in miles) for proximity search","type":"number","format":"float","required":false},{"in":"query","name":"sort","description":"Sort by attribute and direction (e.g., 'date:desc')","type":"string","default":"date:desc","enum":["date:asc","date:desc","likes_count:asc","likes_count:desc","duration:asc","duration:desc","updated_at:asc","updated_at:desc"],"required":false},{"in":"query","name":"audio_status","description":"Filter by audio status: 'any' (default), 'complete', 'partial', 'missing', 'complete_or_partial'","type":"string","default":"any","enum":["any","complete","partial","missing","complete_or_partial"],"required":false},{"in":"query","name":"year","description":"Filter shows by a specific year","type":"integer","format":"int32","required":false},{"in":"query","name":"year_range","description":"Filter shows by a range of years (e.g., '1987-1988')","type":"string","required":false},{"in":"query","name":"venue_slug","description":"Filter shows by the slug of the venue","type":"string","required":false},{"in":"query","name":"tag_slug","description":"Filter shows by the slug of an associated tag","type":"string","required":false},{"in":"query","name":"start_date","description":"Filter shows from this start date (inclusive)","type":"string","default":"1970-01-01","required":false},{"in":"query","name":"end_date","description":"Filter shows up to this end date (inclusive)","type":"string","default":"2070-01-01","required":false},{"in":"query","name":"us_state","description":"Filter shows by US state (abbreviations)","type":"string","required":false},{"in":"query","name":"liked_by_user","description":"If true, fetch only those shows liked by the current user","type":"boolean","default":false,"required":false}],"responses":{"200":{"description":"Fetch a list of shows","schema":{"$ref":"#/definitions/ApiV2_Entities_Show"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["shows"],"operationId":"getShows"}},"/shows/random":{"get":{"summary":"Fetch a random show","description":"Fetch a random show","produces":["application/json"],"responses":{"200":{"description":"Fetch a random show","schema":{"$ref":"#/definitions/ApiV2_Entities_Show"}}},"tags":["shows"],"operationId":"getShowsRandom"}},"/shows/{date}":{"get":{"summary":"Fetch a show by date","description":"Fetch a specific show by its date, including associated tracks and tags","produces":["application/json"],"parameters":[{"in":"path","name":"date","description":"Date in the format YYYY-MM-DD","type":"string","required":true},{"in":"query","name":"audio_status","description":"Filter by audio status: 'any' (default), 'complete', 'partial', 'missing', 'complete_or_partial'","type":"string","default":"any","enum":["any","complete","partial","missing","complete_or_partial"],"required":false}],"responses":{"200":{"description":"Fetch a show by date","schema":{"$ref":"#/definitions/ApiV2_Entities_Show"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["shows"],"operationId":"getShowsDate"}},"/shows/day_of_year/{date}":{"get":{"summary":"Fetch shows played on a day of the year","description":"Fetch all shows that occurred on a specific day of the year based on the specified date","produces":["application/json"],"parameters":[{"in":"path","name":"date","description":"Date in the format YYYY-MM-DD","type":"string","required":true},{"in":"query","name":"sort","description":"Sort by attribute and direction (e.g., 'date:desc')","type":"string","default":"date:desc","enum":["date:asc","date:desc","likes_count:asc","likes_count:desc","duration:asc","duration:desc","updated_at:asc","updated_at:desc"],"required":false},{"in":"query","name":"audio_status","description":"Filter by audio status: 'any' (default), 'complete', 'partial', 'missing', 'complete_or_partial'","type":"string","default":"any","enum":["any","complete","partial","missing","complete_or_partial"],"required":false}],"responses":{"200":{"description":"Fetch shows played on a day of the year","schema":{"$ref":"#/definitions/ApiV2_Entities_Show"}}},"tags":["shows"],"operationId":"getShowsDayOfYearDate"}},"/shows/request_album_zip":{"post":{"summary":"Request a ZIP archive of a show's tracks","description":"Request a ZIP archive of a show's tracks, cover art, and taper notes","produces":["application/json"],"consumes":["application/json"],"parameters":[{"name":"postShowsRequestAlbumZip","in":"body","required":true,"schema":{"$ref":"#/definitions/postShowsRequestAlbumZip"}}],"responses":{"409":{"description":"Download already requested"}},"tags":["shows"],"operationId":"postShowsRequestAlbumZip"}},"/songs":{"get":{"summary":"Fetch a list of songs","description":"Fetch a filtered, sorted, paginated list of songs","produces":["application/json"],"parameters":[{"in":"query","name":"page","description":"Page number for pagination (min: 1)","type":"integer","format":"int32","default":1,"required":false},{"in":"query","name":"per_page","description":"Number of items per page for pagination (min: 1, max: 1000)","type":"integer","format":"int32","default":10,"required":false},{"in":"query","name":"audio_status","description":"Filter by audio status: 'any' (default), 'complete', 'partial', 'missing', 'complete_or_partial'","type":"string","default":"any","enum":["any","complete","partial","missing","complete_or_partial"],"required":false},{"in":"query","name":"sort","description":"Sort by attribute and direction (e.g., 'title:asc')","type":"string","default":"title:asc","enum":["title:asc","title:desc","tracks_count:asc","tracks_count:desc","updated_at:asc","updated_at:desc"],"required":false},{"in":"query","name":"first_char","description":"Filter songs by the first character of the song title (case-insensitive)","type":"string","enum":["A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z","#"],"required":false}],"responses":{"200":{"description":"Fetch a list of songs","schema":{"$ref":"#/definitions/ApiV2_Entities_Song"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["songs"],"operationId":"getSongs"}},"/songs/{slug}":{"get":{"summary":"Fetch a song","description":"Fetch a song by its slug","produces":["application/json"],"parameters":[{"in":"path","name":"slug","description":"Slug of the song","type":"string","required":true}],"responses":{"200":{"description":"Fetch a song","schema":{"$ref":"#/definitions/ApiV2_Entities_Song"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["songs"],"operationId":"getSongsSlug"}},"/tags":{"get":{"summary":"Fetch a list of tags","description":"Fetch a list of all tags, sorted alphabetically by name","produces":["application/json"],"responses":{"200":{"description":"Fetch a list of tags","schema":{"$ref":"#/definitions/ApiV2_Entities_Tag"}}},"tags":["tags"],"operationId":"getTags"}},"/tours":{"get":{"summary":"Fetch a list of tours","description":"Fetch a sorted, paginated list of tours","produces":["application/json"],"parameters":[{"in":"query","name":"page","description":"Page number for pagination (min: 1)","type":"integer","format":"int32","default":1,"required":false},{"in":"query","name":"per_page","description":"Number of items per page for pagination (min: 1, max: 1000)","type":"integer","format":"int32","default":10,"required":false},{"in":"query","name":"sort","description":"Sort by attribute and direction (e.g., 'starts_on:asc')","type":"string","default":"starts_on:asc","enum":["name:asc","name:desc","starts_on:asc","starts_on:desc","ends_on:asc","ends_on:desc","shows_count:asc","shows_count:desc","updated_at:asc","updated_at:desc"],"required":false}],"responses":{"200":{"description":"Fetch a list of tours","schema":{"$ref":"#/definitions/ApiV2_Entities_Tour"}}},"tags":["tours"],"operationId":"getTours"}},"/tours/{slug}":{"get":{"summary":"Fetch a tour","description":"Fetch a tour by its slug, including associated shows","produces":["application/json"],"parameters":[{"in":"path","name":"slug","description":"Slug of the tour","type":"string","required":true}],"responses":{"200":{"description":"Fetch a tour","schema":{"$ref":"#/definitions/ApiV2_Entities_Tour"}}},"tags":["tours"],"operationId":"getToursSlug"}},"/tracks":{"get":{"summary":"Fetch a list of tracks","description":"Fetch a filtered, sorted, paginated list of tracks","produces":["application/json"],"parameters":[{"in":"query","name":"page","description":"Page number for pagination (min: 1)","type":"integer","format":"int32","default":1,"required":false},{"in":"query","name":"per_page","description":"Number of items per page for pagination (min: 1, max: 1000)","type":"integer","format":"int32","default":10,"required":false},{"in":"query","name":"audio_status","description":"Filter by audio status: 'any' (default), 'complete', 'partial', 'missing', 'complete_or_partial'","type":"string","default":"any","enum":["any","complete","partial","missing","complete_or_partial"],"required":false},{"in":"query","name":"sort","description":"Sort by attribute and direction (e.g., 'id:asc')","type":"string","default":"id:asc","enum":["id:asc","id:desc","title:asc","title:desc","likes_count:asc","likes_count:desc","duration:asc","duration:desc","date:asc","date:desc","updated_at:asc","updated_at:desc"],"required":false},{"in":"query","name":"tag_slug","description":"Filter tracks by the slug of the tag","type":"string","required":false},{"in":"query","name":"song_slug","description":"Filter tracks by the slug of the song","type":"string","required":false},{"in":"query","name":"liked_by_user","description":"Filter by tracks liked by the current user","type":"boolean","default":false,"required":false},{"in":"query","name":"start_date","description":"Filter tracks from shows starting from this date (inclusive)","type":"string","required":false},{"in":"query","name":"end_date","description":"Filter tracks from shows up to this date (inclusive)","type":"string","required":false},{"in":"query","name":"year","description":"Filter tracks from shows in a specific year","type":"integer","format":"int32","required":false},{"in":"query","name":"year_range","description":"Filter tracks from shows in a range of years (e.g., '1987-1988')","type":"string","required":false}],"responses":{"200":{"description":"Fetch a list of tracks","schema":{"$ref":"#/definitions/ApiV2_Entities_Track"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["tracks"],"operationId":"getTracks"}},"/tracks/{id}":{"get":{"summary":"Fetch a track by ID","description":"Fetch a track by its ID, including show details, tags, and songs","produces":["application/json"],"parameters":[{"in":"path","name":"id","description":"ID of the track","type":"integer","format":"int32","required":true}],"responses":{"200":{"description":"Fetch a track by ID","schema":{"$ref":"#/definitions/ApiV2_Entities_Track"}},"400":{"description":"Bad Request","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/ApiV2_Entities_ApiResponse"}}},"tags":["tracks"],"operationId":"getTracksId"}},"/venues":{"get":{"summary":"Fetch a list of venues","description":"Fetch a filtered, sorted, paginated list of venues","produces":["application/json"],"parameters":[{"in":"query","name":"page","description":"Page number for pagination (min: 1)","type":"integer","format":"int32","default":1,"required":false},{"in":"query","name":"per_page","description":"Number of items per page for pagination (min: 1, max: 1000)","type":"integer","format":"int32","default":10,"required":false},{"in":"query","name":"lat","description":"Latitude for proximity search","type":"number","format":"float","required":false},{"in":"query","name":"lng","description":"Longitude for proximity search","type":"number","format":"float","required":false},{"in":"query","name":"distance","description":"Distance (in miles) for proximity search","type":"number","format":"float","required":false},{"in":"query","name":"audio_status","description":"Filter by audio status: 'any' (default), 'complete', 'partial', 'missing', 'complete_or_partial'","type":"string","default":"any","enum":["any","complete","partial","missing","complete_or_partial"],"required":false},{"in":"query","name":"sort","description":"Sort by attribute and direction (e.g., 'name:asc')","type":"string","default":"name:asc","enum":["name:asc","name:desc","shows_count:asc","shows_count:desc","updated_at:asc","updated_at:desc"],"required":false},{"in":"query","name":"first_char","description":"Filter venues by the first character of the venue name (case-insensitive)","type":"string","enum":["A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z","#"],"required":false}],"responses":{"200":{"description":"Fetch a list of venues","schema":{"$ref":"#/definitions/ApiV2_Entities_Venue"}}},"tags":["venues"],"operationId":"getVenues"}},"/venues/{slug}":{"get":{"summary":"Fetch a venue","description":"Fetch a venue by its slug","produces":["application/json"],"parameters":[{"in":"path","name":"slug","description":"Slug of the venue","type":"string","required":true}],"responses":{"200":{"description":"Fetch a venue","schema":{"$ref":"#/definitions/ApiV2_Entities_Venue"}}},"tags":["venues"],"operationId":"getVenuesSlug"}},"/years":{"get":{"summary":"Fetch a list of years","description":"Fetch a list of years during which Phish has performed, including era designations, the number of shows performed each year, unique venues count, and selected cover art.","produces":["application/json"],"responses":{"200":{"description":"Fetch a list of years","schema":{"$ref":"#/definitions/ApiV2_Entities_Year"}}},"tags":["years"],"operationId":"getYears"}}},"definitions":{"ApiV2_Entities_Announcement":{"type":"object","properties":{"title":{"type":"string","description":"Title of the announcement"},"description":{"type":"string","description":"Description of the announcement"},"url":{"type":"string","description":"URL related to the announcement (usually a Show)"},"created_at":{"type":"string","description":"Timestamp of initial creation"}},"required":["title","description","url","created_at"],"description":"ApiV2_Entities_Announcement model"},"postAuthCreateUser":{"type":"object","properties":{"username":{"type":"string","description":"Username"},"email":{"type":"string","description":"Email"},"password":{"type":"string","description":"Password"},"password_confirmation":{"type":"string","description":"Password confirmation"}},"required":["username","email","password","password_confirmation"],"description":"Create a new user"},"ApiV2_Entities_LoginResponse":{"type":"object","properties":{"jwt":{"type":"string","description":"JWT"},"username":{"type":"string","description":"User's username"},"email":{"type":"string","description":"User's email address"}},"required":["jwt","username","email"],"description":"ApiV2_Entities_LoginResponse model"},"postAuthLogin":{"type":"object","properties":{"email":{"type":"string","description":"User email"},"password":{"type":"string","description":"User password"}},"required":["email","password"],"description":"User login via email and password"},"ApiV2_Entities_User":{"type":"object","properties":{"username":{"type":"string","description":"Username of the user"},"email":{"type":"string","description":"Email address of the user"},"created_at":{"type":"string","description":"Timestamp of initial creation"},"username_updated_at":{"type":"string","description":"Timestamp of when the user's username was last updated"}},"required":["username","email","created_at","username_updated_at"],"description":"ApiV2_Entities_User model"},"postAuthRequestPasswordReset":{"type":"object","properties":{"email":{"type":"string","description":"User email"}},"required":["email"],"description":"Request password reset email"},"ApiV2_Entities_ApiResponse":{"type":"object","properties":{"message":{"type":"string","description":"Error or success message"}},"required":["message"],"description":"ApiV2_Entities_ApiResponse model"},"postAuthResetPassword":{"type":"object","properties":{"token":{"type":"string","description":"Reset token from email"},"password":{"type":"string","description":"New password"},"password_confirmation":{"type":"string","description":"Password confirmation"}},"required":["token","password","password_confirmation"],"description":"Reset a user's password via reset token"},"postLikes":{"type":"object","properties":{"likable_type":{"type":"string","description":"Type of the likable object","enum":["Show","Track","Playlist"]},"likable_id":{"type":"integer","format":"int32","description":"ID of the likable object"}},"required":["likable_type","likable_id"],"description":"Like or unlike a show, track, or playlist"},"ApiV2_Entities_Playlist":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"ID of the playlist"},"slug":{"type":"string","description":"The unique slug for the playlist"},"name":{"type":"string","description":"The display name of the playlist"},"description":{"type":"string","description":"The description of the playlist"},"username":{"type":"string"},"duration":{"type":"integer","format":"int32","description":"The total duration of all tracks in the playlist, in milliseconds"},"entries":{"allOf":[{"$ref":"#/definitions/ApiV2_Entities_PlaylistTrack"}],"description":"The entries in the playlist, which themselves include the track along with its position and other metadata"},"tracks_count":{"type":"integer","format":"int32","description":"The number of tracks in the playlist"},"likes_count":{"type":"integer","format":"int32","description":"The number of likes the playlist has received"},"created_at":{"type":"string","description":"Timestamp of initial creation"},"updated_at":{"type":"string","description":"Timestamp of most recent update"},"published":{"type":"boolean","description":"Indicates if the playlist is listed publicly for other users to browse and search"},"liked_by_user":{"type":"boolean","description":"Indicates if the current user has liked this playlist"}},"required":["id","slug","name","description","username","duration","tracks_count","likes_count","created_at","updated_at","published","liked_by_user"],"description":"ApiV2_Entities_Playlist model"},"ApiV2_Entities_PlaylistTrack":{"type":"object","properties":{"track":{"type":"Object","description":"The associated track details"},"position":{"type":"integer","format":"int32","description":"Position of the track in the setlist"},"duration":{"type":"integer","format":"int32","description":"Duration of track excerpt in milliseconds. If starts_at_second and ends_at_second are both blank, this will be the full duration of the track."},"starts_at_second":{"type":"integer","format":"int32","description":"If present, indicates the second at which to start playing the track"},"ends_at_second":{"type":"integer","format":"int32","description":"If present, indicates the second at which to stop playing the track"}},"required":["position","duration","starts_at_second","ends_at_second"]},"postPlaylists":{"type":"object","properties":{"name":{"type":"string","description":"Name of the playlist"},"slug":{"type":"string","description":"Slug of the playlist"},"description":{"type":"string","description":"Description of the playlist"},"published":{"type":"boolean","description":"Published flag (true to make browseable/searchable by public users, false to make private)"},"track_ids":{"type":"array","description":"Array of track IDs that make up the playlist","items":{"type":"integer","format":"int32"}},"starts_at_second":{"type":"array","description":"Array of starting positions of associated track selections in track_ids array","items":{"type":"integer","format":"int32"}},"ends_at_second":{"type":"array","description":"Array of ending positions of associated track selections in track_ids array","items":{"type":"integer","format":"int32"}}},"required":["name","slug","description","published","track_ids","starts_at_second","ends_at_second"],"description":"Create a new playlist"},"putPlaylistsId":{"type":"object","properties":{"name":{"type":"string","description":"Name of the playlist"},"slug":{"type":"string","description":"Slug of the playlist"},"description":{"type":"string","description":"Description of the playlist"},"published":{"type":"boolean","description":"Published flag (true to make browseable/searchable by public users, false to make private)"},"track_ids":{"type":"array","description":"Array of track IDs that make up the playlist","items":{"type":"integer","format":"int32"}},"starts_at_second":{"type":"array","description":"Array of starting positions of associated track selections in track_ids array","items":{"type":"integer","format":"int32"}},"ends_at_second":{"type":"array","description":"Array of ending positions of associated track selections in track_ids array","items":{"type":"integer","format":"int32"}}},"required":["name","slug","description","published","track_ids","starts_at_second","ends_at_second"],"description":"Update an existing playlist"},"ApiV2_Entities_MissingContentReport":{"type":"object","properties":{"missing_shows":{"type":"array","items":{"type":"Array[Object]"},"description":"A list of shows for which there is no circulated recording. Each object contains the date, venue_name, and location."},"incomplete_shows":{"type":"array","items":{"type":"Array[Object]"},"description":"A list of shows for which there is only a partial recording. Each object contains the date, venue_name, and location."}},"required":["missing_shows","incomplete_shows"],"description":"ApiV2_Entities_MissingContentReport model"},"ApiV2_Entities_SearchResults":{"type":"object","properties":{"exact_show":{"allOf":[{"$ref":"#/definitions/ApiV2_Entities_Show"}],"description":"The show that exactly matches the specified date (if any). Returns a show object including venue and date information. Null if no exact match is found."},"other_shows":{"type":"array","items":{"type":"Array[Object]"},"description":"Shows that occurred on the same day of the year as the search date, from any year. Returns an array of show objects including date and venue details. Empty array if no shows are found."},"songs":{"type":"array","items":{"$ref":"#/definitions/ApiV2_Entities_Song"},"description":"An array of songs that match the search term in title or alias. Each song object includes title and artist details. Empty if no songs match."},"venues":{"type":"array","items":{"$ref":"#/definitions/ApiV2_Entities_Venue"},"description":"An array of venues where the name, abbreviation, city, state, or country matches the search term. Each venue object contains detailed venue information. Returns an empty array if no venues match."},"tracks":{"type":"array","items":{"type":"Array[Object]"},"description":"Tracks that match the search term in title. Does not include tracks where the title matches a song title to avoid duplicates. Each track object includes show and track details. Empty array if no tracks match."},"tags":{"type":"array","items":{"$ref":"#/definitions/ApiV2_Entities_Tag"},"description":"Tags that match the search term either in name or description. Each tag object includes the tag name and details. Returns an empty array if no tags match."},"playlists":{"type":"array","items":{"type":"Array[Object]"},"description":"An array of playlists whose name matches the search term. Does not include track information."}},"required":["exact_show","other_shows","songs","venues","tracks","tags","playlists"],"description":"ApiV2_Entities_SearchResults model"},"ApiV2_Entities_Show":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"ID of the show"},"date":{"type":"string","format":"date","description":"Date of the show"},"audio_status":{"type":"string","description":"Audio status of the show: 'complete', 'partial', or 'missing'"},"cover_art_urls":{"type":"Object","description":"Object containing named URLs for variants of raw cover art images"},"album_cover_url":{"type":"string","description":"URL of album cover image (text overlayed on cover art)"},"album_zip_url":{"type":"string","description":"URL of zipfile containing the show's MP3s, cover art, and taper notes"},"duration":{"type":"integer","format":"int32","description":"Duration of the show in milliseconds. Excludes soundcheck (S) and pre-show (P) tracks."},"admin_notes":{"type":"string","description":"Administrator's notes related to the show"},"tour_name":{"type":"string","description":"Name of the tour the show belongs to"},"venue_name":{"type":"string","description":"Name of the venue where the show took place, reflecting the name at the time (not necessarily the current name)"},"venue":{"allOf":[{"$ref":"#/definitions/ApiV2_Entities_Venue"}],"description":"Venue where the show took place"},"taper_notes":{"type":"string","description":"Notes from the taper of the show"},"likes_count":{"type":"integer","format":"int32","description":"Number of likes the show has received"},"performance_gap_value":{"type":"integer","format":"int32","description":"The value to use when calculating song performance gaps (default 1). Some records in the database represent multiple shows that took place on the same date (\u003e1) while others were performances that don't count toward gaps and personal stats (0)."},"created_at":{"type":"string","description":"Timestamp of initial creation"},"updated_at":{"type":"string","description":"Timestamp of most recent update"},"tags":{"type":"array","items":{"$ref":"#/definitions/ApiV2_Entities_ShowTag"},"description":"Tags associated with the show"},"tracks":{"type":"array","items":{"type":"string"},"description":"Tracks associated with the show, included only on individual show requests"},"liked_by_user":{"type":"string"},"previous_show_date":{"type":"string","format":"date","description":"Date of the previous show (including missing audio)"},"next_show_date":{"type":"string","format":"date","description":"Date of the next show (including missing audio)"},"previous_show_date_with_audio":{"type":"string","format":"date","description":"Date of the previous show that has audio (or last show that has audio if none exists)"},"next_show_date_with_audio":{"type":"string","format":"date","description":"Date of the next show that has audio (or first show that has audio if none exists)"}},"required":["id","date","audio_status","cover_art_urls","album_cover_url","album_zip_url","duration","admin_notes","tour_name","venue_name","venue","taper_notes","likes_count","performance_gap_value","created_at","updated_at","tags","liked_by_user","previous_show_date","next_show_date","previous_show_date_with_audio","next_show_date_with_audio"],"description":"ApiV2_Entities_Show model"},"ApiV2_Entities_Venue":{"type":"object","properties":{"slug":{"type":"string","description":"Unique slug identifier for the venue"},"name":{"type":"string","description":"Name of the venue"},"other_names":{"type":"array","items":{"type":"string"},"description":"Other names or aliases of the venue"},"latitude":{"type":"number","format":"float","description":"Latitude of the venue"},"longitude":{"type":"number","format":"float","description":"Longitude of the venue"},"city":{"type":"string","description":"City where the venue is located"},"state":{"type":"string","description":"State or region where the venue is located"},"country":{"type":"string","description":"Country where the venue is located"},"location":{"type":"string","description":"Full location of the venue (city, state, country)"},"map_snapshot_url":{"type":"string","description":"URL for venue map snapshot image"},"shows_count":{"type":"integer","format":"int32","description":"Number of shows that have taken place at the venue"},"shows_with_audio_count":{"type":"integer","format":"int32","description":"Number of shows that have taken place at the venue that have audio"},"created_at":{"type":"string","description":"Timestamp of initial creation"},"updated_at":{"type":"string","description":"Timestamp of most recent update"}},"required":["slug","name","other_names","latitude","longitude","city","state","country","location","map_snapshot_url","shows_count","shows_with_audio_count","created_at","updated_at"],"description":"ApiV2_Entities_Venue model"},"ApiV2_Entities_ShowTag":{"type":"object","properties":{"name":{"type":"string","description":"The name of the tag"},"description":{"type":"string","description":"A description of the tag"},"color":{"type":"string","description":"The color of the tag"},"priority":{"type":"integer","format":"int32","description":"The display priority of the tag"},"notes":{"type":"string","description":"Optional notes related to this instance of the tag"}},"required":["name","description","color","priority","notes"]},"ApiV2_Entities_Song":{"type":"object","properties":{"slug":{"type":"string","description":"Unique slug identifier for the song"},"title":{"type":"string","description":"Title of the song"},"alias":{"type":"string","description":"Alias or alternate title of the song, if any"},"original":{"type":"boolean","description":"Indicates if the song is an original composition"},"artist":{"type":"string","description":"Artist associated with the song (if not original)"},"tracks_count":{"type":"integer","format":"int32","description":"Number of tracks associated with the song"},"tracks_with_audio_count":{"type":"integer","format":"int32","description":"Number of tracks associated with the song that have audio"},"created_at":{"type":"string","description":"Timestamp of initial creation"},"updated_at":{"type":"string","description":"Timestamp of most recent update"},"previous_performance_gap":{"type":"integer","format":"int32","description":"Count of shows since the last performance of the song"},"previous_performance_slug":{"type":"string","description":"Slug of the last performance of the song"},"next_performance_gap":{"type":"integer","format":"int32","description":"Count of shows until the next performance of the song"},"next_performance_slug":{"type":"string","description":"Slug of the next performance of the song"},"previous_performance_gap_with_audio":{"type":"integer","format":"int32","description":"Count of shows since the last performance of the song where audio is present"},"previous_performance_slug_with_audio":{"type":"string","description":"Slug of the last performance of the song where audio is present"},"next_performance_gap_with_audio":{"type":"integer","format":"int32","description":"Count of shows until the next performance of the song where audio is present"},"next_performance_slug_with_audio":{"type":"string","description":"Slug of the next performance of the song where audio is present"}},"required":["slug","title","alias","original","artist","tracks_count","tracks_with_audio_count","created_at","updated_at"],"description":"ApiV2_Entities_Song model"},"ApiV2_Entities_Tag":{"type":"object","properties":{"slug":{"type":"string","description":"Unique slug identifier for the tag"},"name":{"type":"string","description":"Name of the tag"},"description":{"type":"string","description":"Description of the tag"},"priority":{"type":"integer","format":"int32","description":"Priority level of the tag"},"shows_count":{"type":"integer","format":"int32","description":"Number of shows associated with the tag"},"tracks_count":{"type":"integer","format":"int32","description":"Number of tracks associated with the tag"},"group":{"type":"string","description":"Group or category of the tag"}},"required":["slug","name","description","priority","shows_count","tracks_count","group"],"description":"ApiV2_Entities_Tag model"},"postShowsRequestAlbumZip":{"type":"object","properties":{"date":{"type":"string","description":"Date in the format YYYY-MM-DD"}},"required":["date"],"description":"Request a ZIP archive of a show's tracks"},"ApiV2_Entities_Tour":{"type":"object","properties":{"slug":{"type":"string","description":"Unique slug identifier for the tour"},"name":{"type":"string","description":"Name of the tour"},"shows_count":{"type":"integer","format":"int32","description":"Number of shows associated with the tour"},"shows_with_audio_count":{"type":"integer","format":"int32","description":"Number of shows associated with the tour that have audio"},"starts_on":{"type":"string","format":"date","description":"Start date of the tour"},"ends_on":{"type":"string","format":"date","description":"End date of the tour"},"created_at":{"type":"string","description":"Timestamp of initial creation"},"updated_at":{"type":"string","description":"Timestamp of most recent update"},"shows":{"allOf":[{"$ref":"#/definitions/ApiV2_Entities_Show"}],"description":"List of shows associated with the tour, included only on individual tour requests"}},"required":["slug","name","shows_count","shows_with_audio_count","starts_on","ends_on","created_at","updated_at"],"description":"ApiV2_Entities_Tour model"},"ApiV2_Entities_Track":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"ID of the track"},"slug":{"type":"string","description":"Unique slug identifier for the track"},"title":{"type":"string","description":"Title of the track"},"position":{"type":"integer","format":"int32","description":"Position of the track in the setlist"},"duration":{"type":"integer","format":"int32","description":"Duration of the track in milliseconds"},"jam_starts_at_second":{"type":"integer","format":"int32","description":"Second at which the jam section starts in the track"},"set_name":{"type":"integer","format":"int32","description":"Set number this track belongs to"},"exclude_from_stats":{"type":"boolean","description":"Whether this track should be excluded from performance gap and other stats calculations"},"likes_count":{"type":"integer","format":"int32","description":"Number of likes the track has received"},"audio_status":{"type":"string","description":"Audio status of the track: 'complete', 'partial', or 'missing'"},"mp3_url":{"type":"string","description":"URL to the MP3 file of the track"},"waveform_image_url":{"type":"string","description":"URL to the waveform image of the track"},"tags":{"type":"array","items":{"$ref":"#/definitions/ApiV2_Entities_TrackTag"},"description":"Tags associated with the track"},"created_at":{"type":"string","description":"Timestamp of initial creation"},"updated_at":{"type":"string","description":"Timestamp of most recent update"},"show_date":{"type":"string","format":"date","description":"Date of the show that the track belongs to"},"show_cover_art_urls":{"type":"Object","description":"Object containing named URLs for variants of raw cover art images"},"show_album_cover_url":{"type":"Object","description":"URL of album cover image (text overlayed on cover art)"},"venue_slug":{"type":"string","description":"Unique slug of the venue where the show took place"},"venue_name":{"type":"string","description":"Name the venue where the show took place, reflecting the name used on the date of the show"},"venue_location":{"type":"string","description":"City and state where the venue of the show was located"},"show":{"allOf":[{"$ref":"#/definitions/ApiV2_Entities_Show"}],"description":"Show this track belongs to"},"songs":{"type":"array","items":{"type":"string"},"description":"Songs associated with the track"},"liked_by_user":{"type":"string"}},"required":["id","slug","title","position","duration","jam_starts_at_second","set_name","exclude_from_stats","likes_count","audio_status","mp3_url","waveform_image_url","tags","created_at","updated_at","show_date","show_cover_art_urls","show_album_cover_url","venue_slug","venue_name","venue_location","songs","liked_by_user"],"description":"ApiV2_Entities_Track model"},"ApiV2_Entities_TrackTag":{"type":"object","properties":{"name":{"type":"string","description":"The name of the tag"},"description":{"type":"string","description":"A description of the tag"},"color":{"type":"string","description":"The color of the tag"},"priority":{"type":"integer","format":"int32","description":"The display priority of the tag"},"notes":{"type":"string","description":"Optional notes related to this instance of the tag"},"starts_at_second":{"type":"integer","format":"int32","description":"The starting second of the tag within the track audio"},"ends_at_second":{"type":"integer","format":"int32","description":"The ending second of the tag within the track audio"},"transcript":{"type":"string","description":"Transcript of the tagged portion of the track, if available"}},"required":["name","description","color","priority","notes","starts_at_second","ends_at_second","transcript"]},"ApiV2_Entities_Year":{"type":"object","properties":{"period":{"type":"string","description":"The year or period being represented (e.g. \"1997\", \"1983-1987\")"},"shows_count":{"type":"integer","format":"int32","description":"Number of shows that were performed during this period"},"shows_with_audio_count":{"type":"integer","format":"int32","description":"Number of shows that were performed during this period that have audio"},"shows_duration":{"type":"integer","format":"int32","description":"Total duration in milliseconds of all shows performed during this period"},"venues_count":{"type":"integer","format":"int32","description":"Number of unique venues that shows were performed at during this period"},"venues_with_audio_count":{"type":"integer","format":"int32","description":"Number of unique venues that shows were performed at during this period that have audio"},"era":{"type":"string","description":"The era associated with this period (\"1.0\", \"2.0\", etc.)"},"cover_art_urls":{"type":"array","description":"Cover art URLs taken from the last show in the period"}},"required":["period","shows_count","shows_with_audio_count","shows_duration","venues_count","venues_with_audio_count","era","cover_art_urls"],"description":"ApiV2_Entities_Year model"}}}