Show catalog

GET /v1/public/shows returns the current public show catalog. It requires no authentication.

This unauthenticated, read-only endpoint supports direct browser requests from any origin. GET and OPTIONS responses use Access-Control-Allow-Origin: *.

Request

Query parameters

All parameters are optional. The default response contains up to 24 upcoming shows.

Parameter	Type	Description
`when`	`string`	Time window: `upcoming` (default), `weekend`, or `past`.
`city`	`string`	Case-insensitive city filter.
`country`	`string`	Case-insensitive country filter.
`continent`	`string`	Continent filter.
`artist`	`string`	Public artist username. The API also accepts the artist ID as a fallback.
`limit`	`integer`	Number of rows to return, from `1` to `48`. The default is `24`.
`cursor`	`string`	Opaque cursor from the previous response's `pagination.next_cursor`.

Location and artist filters can be combined. The API applies all supplied filters before it orders and paginates the result.

Example request

curl --fail-with-body \
  'https://api.b90hq.app/v1/public/shows?when=upcoming&city=Berlin&limit=10'

Response

The response contains data and a pagination object. Top-level show fields use camelCase. Artist objects use the public artist field names shown in the example.

{
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "shortCode": "berlin-show",
      "title": "HQ at the venue",
      "eventDate": "2026-10-10",
      "startTime": "2026-10-10T22:00:00.000Z",
      "endTime": "2026-10-11T04:00:00.000Z",
      "isPlaytimeTBA": false,
      "timezone": "Europe/Berlin",
      "locationName": "The venue",
      "locationCity": "Berlin",
      "locationCountry": "Germany",
      "continent": "Europe",
      "coordinates": {
        "latitude": 52.52,
        "longitude": 13.405
      },
      "venuePlaceId": "place-id",
      "webUrl": "https://joinhq.app/show/berlin-show",
      "thumbnailUrl": "https://cdn.example.com/show.jpg",
      "totalRsvps": 42,
      "artists": [
        {
          "artist_id": "00000000-0000-4000-8000-000000000002",
          "display_name": "Artist name",
          "username": "artist",
          "avatar_url": "https://cdn.example.com/avatar.jpg",
          "avatar_thumb_url": "https://cdn.example.com/avatar-thumb.jpg",
          "community_id": "00000000-0000-4000-8000-000000000003",
          "community_name": "Artist community",
          "start_time": "2026-10-10T22:00:00.000Z",
          "end_time": "2026-10-11T00:00:00.000Z",
          "is_playtime_tba": false
        }
      ]
    }
  ],
  "pagination": {
    "limit": 10,
    "has_next": true,
    "next_cursor": "opaque-cursor"
  }
}

Show fields

Field	Type	Description
`id`	`string`	Stable show ID.
`shortCode`	`string`	Public short code.
`title`	`string`	Show title.
`eventDate`	`string`	Event date in `YYYY-MM-DD` format.
`startTime`, `endTime`	`string`	ISO 8601 timestamps.
`isPlaytimeTBA`	`boolean`	Aggregate flag: `true` only when all artist playtime rows are to be announced. Use the matching `artists[].is_playtime_tba` value for one artist.
`timezone`	`string`	IANA timezone for the event.
`locationName`, `locationCity`, `locationCountry`	`string`	Public venue and location fields.
`continent`	`string \| null`	Normalized continent, when available.
`coordinates`	`object \| null`	Public `{ latitude, longitude }` coordinates, when available.
`venuePlaceId`	`string \| null`	Public venue provider place ID, when available.
`webUrl`	`string \| null`	Show URL, when available.
`thumbnailUrl`	`string \| null`	Public show image URL, when available.
`totalRsvps`	`integer`	Current total RSVP count.
`artists`	`array`	Public artist and timetable rows.

Nullable fields are returned as null. The artists array can be empty.

Pagination and ordering

Use pagination.next_cursor as the next request's cursor value. Treat it as opaque: do not decode or construct it yourself.

The API uses stable keyset pagination. upcoming and weekend results are ordered by startTime and then id in ascending order. past results use the same fields in descending order. When has_next is false, next_cursor is null.

The top-level isPlaytimeTBA value is an all-artists aggregate. For an individual artist, use the matching artists[].is_playtime_tba value. Any row marked with is_playtime_tba: true still contains fallback start_time and end_time values for scheduling; display the TBA state instead of presenting those fallback times as confirmed playtimes.

Errors

Malformed query parameters return a JSON error with status 400. The current error values are:

Error	Cause
`invalid_when`	`when` is not `upcoming`, `weekend`, or `past`.
`invalid_limit`	`limit` is not an integer from `1` to `48`.
`invalid_cursor`	`cursor` is not a valid cursor returned by this endpoint.
`invalid_continent`	`continent` is not a supported continent value.