{
  "openapi": "3.1.0",
  "info": {
    "title": "The List Access — public event and location API",
    "version": "1.4.0",
    "description": "Read-only selection of upcoming events. Missing facts remain absent. checkedAt is an observation; modifiedAt tracks known content changes. Follow sourceUrl for official conditions and url for attribution. A verified group is not a personal guestlist confirmation. Public GET responses can be cached for 30 seconds; underlying reads may be up to 30 seconds old. ETag/If-None-Match support 304. Follow all next pages. Raw synchronization feeds are not the enriched content API. Public page directory: /, /guestlists, /tickets, /events, /hoe-het-werkt, /highlights, /locaties, /faq and /event-aanmelden. /llms.txt links all public sources. Private analytics and organizer submissions are not public read APIs. Organizer pages are linked from event pages and the sitemap; organizer search uses q, not an organizer API parameter. Last verified guestlist links can be retained during updater outages and do not automatically expire after 12 hours. Price review dates and status do not guarantee current stock. regularTicket describes regular phases and their admission conditions. The API excludes ended events even for past date filters. ticketOptions are the canonical field-evidenced commercial records; legacy ticketDeal/regularTicket/ticketOffer are compatibility summaries. Conflicts hide numeric offers. Each public surface uses the same enriched record."
  },
  "servers": [
    {
      "url": "https://thelistaccess.nl"
    }
  ],
  "paths": {
    "/api/events": {
      "get": {
        "operationId": "listEvents",
        "summary": "Find upcoming club nights and dance festivals",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search words in title, artist, organizer, city or venue",
            "schema": {
              "type": "string",
              "maxLength": 150
            }
          },
          {
            "name": "city",
            "in": "query",
            "required": false,
            "description": "Exact city, case insensitive",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "genre",
            "in": "query",
            "required": false,
            "description": "Genre, case insensitive",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Inclusive lower date; defaults to today in Europe/Amsterdam. Ended and cancelled events remain excluded even for past date ranges.",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End of date range",
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "guestlist",
            "in": "query",
            "required": false,
            "description": "Only events with a last verified public The List event-group link; not personal guestlist confirmation.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "maximum": 99999
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Results per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 30,
              "maximum": 100
            }
          },
          {
            "name": "location",
            "in": "query",
            "description": "Stable location ID from /api/locaties",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered and paginated public events; next/previous are absolute URLs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "schemaVersion",
                    "documentation",
                    "filters",
                    "total",
                    "page",
                    "limit",
                    "pages",
                    "next",
                    "previous",
                    "events"
                  ],
                  "properties": {
                    "schemaVersion": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string",
                      "format": "uri"
                    },
                    "filters": {
                      "type": "object",
                      "additionalProperties": {
                        "type": "string"
                      }
                    },
                    "total": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "limit": {
                      "type": "integer"
                    },
                    "pages": {
                      "type": "integer"
                    },
                    "next": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri"
                    },
                    "previous": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "uri"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or repeated parameter",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "error",
                    "documentation"
                  ],
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Only GET and HEAD supported"
          },
          "304": {
            "description": "Unchanged representation for If-None-Match"
          }
        }
      }
    },
    "/api/locaties": {
      "get": {
        "operationId": "listLocations",
        "summary": "Selected clubs and music venues with confirmed upcoming events",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "id",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public catalogue with stable IDs, official sources, observation dates and upcomingEvents",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "schemaVersion",
                    "documentation",
                    "total",
                    "locations"
                  ],
                  "properties": {
                    "total": {
                      "type": "integer"
                    },
                    "locations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Location"
                      }
                    },
                    "schemaVersion": {
                      "type": "string"
                    },
                    "documentation": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or repeated parameter"
          },
          "405": {
            "description": "GET and HEAD only"
          },
          "304": {
            "description": "Unchanged representation for If-None-Match"
          }
        }
      }
    },
    "/feeds/events.json": {
      "get": {
        "operationId": "eventsFeedJSON",
        "summary": "Events today plus 29 days, including ongoing multi-day events",
        "description": "All results, no pagination. RSS/JSON format is invariant across browser and crawler request headers. Use /feeds/events or /feeds/guestlists for HTML. Europe/Amsterdam dates. Cancelled and ended events excluded. Same enriched records as the public agenda. Supports ETag and 30-second caching.",
        "responses": {
          "200": {
            "description": "Feed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Query parameters unsupported"
          }
        },
        "parameters": [
          {
            "name": "raw",
            "in": "query",
            "required": false,
            "description": "Optional compatibility parameter; the URL already always returns its RSS/JSON format.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ]
      }
    },
    "/feeds/events.rss": {
      "get": {
        "operationId": "eventsFeedRSS",
        "summary": "Events today plus 29 days, including ongoing multi-day events",
        "description": "All results, no pagination. RSS/JSON format is invariant across browser and crawler request headers. Use /feeds/events or /feeds/guestlists for HTML. Europe/Amsterdam dates. Cancelled and ended events excluded. Same enriched records as the public agenda. Supports ETag and 30-second caching.",
        "responses": {
          "200": {
            "description": "Feed",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Query parameters unsupported"
          }
        },
        "parameters": [
          {
            "name": "raw",
            "in": "query",
            "required": false,
            "description": "Optional compatibility parameter; the URL already always returns its RSS/JSON format.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ]
      }
    },
    "/feeds/guestlists.json": {
      "get": {
        "operationId": "guestlistsFeedJSON",
        "summary": "Upcoming events with a last-verified guestlist group; not confirmed admission",
        "description": "All results, no pagination. RSS/JSON format is invariant across browser and crawler request headers. Use /feeds/events or /feeds/guestlists for HTML. Europe/Amsterdam dates. Cancelled and ended events excluded. Same enriched records as the public agenda. Supports ETag and 30-second caching.",
        "responses": {
          "200": {
            "description": "Feed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Query parameters unsupported"
          }
        },
        "parameters": [
          {
            "name": "raw",
            "in": "query",
            "required": false,
            "description": "Optional compatibility parameter; the URL already always returns its RSS/JSON format.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ]
      }
    },
    "/feeds/guestlists.rss": {
      "get": {
        "operationId": "guestlistsFeedRSS",
        "summary": "Upcoming events with a last-verified guestlist group; not confirmed admission",
        "description": "All results, no pagination. RSS/JSON format is invariant across browser and crawler request headers. Use /feeds/events or /feeds/guestlists for HTML. Europe/Amsterdam dates. Cancelled and ended events excluded. Same enriched records as the public agenda. Supports ETag and 30-second caching.",
        "responses": {
          "200": {
            "description": "Feed",
            "content": {
              "application/rss+xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Query parameters unsupported"
          }
        },
        "parameters": [
          {
            "name": "raw",
            "in": "query",
            "required": false,
            "description": "Optional compatibility parameter; the URL already always returns its RSS/JSON format.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          }
        ]
      }
    },
    "/feeds/events": {
      "get": {
        "operationId": "eventsFeedBrowser",
        "summary": "Readable event feed for browsers; no JavaScript required",
        "responses": {
          "200": {
            "description": "HTML event list",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/feeds/guestlists": {
      "get": {
        "operationId": "guestlistsFeedBrowser",
        "summary": "Readable event feed for browsers; no JavaScript required",
        "responses": {
          "200": {
            "description": "HTML event list",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Event": {
        "type": "object",
        "required": [
          "slug",
          "name",
          "organizer",
          "date",
          "venue",
          "city",
          "genre",
          "status",
          "sourceUrl",
          "ticketUrl",
          "url",
          "guestlistAvailable",
          "pageModifiedAt"
        ],
        "properties": {
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "organizer": {
            "type": "string",
            "description": "Organizer text, possibly containing co-organizers; a source/venue is not automatically a separately confirmed organizer."
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "time": {
            "type": "string"
          },
          "venue": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "genre": {
            "type": "string"
          },
          "age": {
            "type": "string"
          },
          "lineup": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "endDate": {
            "type": "string",
            "format": "date"
          },
          "startDateTime": {
            "type": "string",
            "format": "date-time"
          },
          "endDateTime": {
            "type": "string",
            "format": "date-time"
          },
          "checkedAt": {
            "type": "string",
            "format": "date-time"
          },
          "modifiedAt": {
            "type": "string",
            "format": "date-time"
          },
          "pageModifiedAt": {
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri"
          },
          "ticketUrl": {
            "type": "string",
            "format": "uri"
          },
          "guestlistUrl": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "string",
            "enum": [
              "tickets",
              "sold-out",
              "tba"
            ],
            "description": "Last stored source status. tickets means a ticket route, not guaranteed stock."
          },
          "image": {
            "type": "string"
          },
          "sourceType": {
            "type": "string",
            "enum": [
              "official",
              "platform"
            ]
          },
          "guestlistAvailable": {
            "type": "boolean",
            "description": "A last verified public event-group link is present; not confirmed admission or a guarantee of a working link."
          },
          "searchAliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "address": {
            "type": "object",
            "required": [
              "streetAddress",
              "addressCountry",
              "sourceUrl",
              "checkedAt"
            ],
            "properties": {
              "streetAddress": {
                "type": "string"
              },
              "postalCode": {
                "type": "string"
              },
              "addressCountry": {
                "type": "string"
              },
              "sourceUrl": {
                "type": "string",
                "format": "uri"
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "locationId": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "performers": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "name",
                "type"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "Person",
                    "PerformingGroup"
                  ]
                }
              }
            }
          },
          "performerSource": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "label": {
                "type": "string"
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "detailsSource": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "ticketDeal": {
            "type": "object",
            "required": [
              "regularPrice",
              "price",
              "currency",
              "url",
              "reviewedAt"
            ],
            "properties": {
              "regularPrice": {
                "type": "number"
              },
              "price": {
                "type": "number"
              },
              "serviceFee": {
                "type": "number",
                "description": "Omitted when unknown; do not assume zero."
              },
              "currency": {
                "type": "string",
                "enum": [
                  "EUR"
                ]
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "reviewedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "description": "Compatibility summary derived from canonical ticketOptions when those are present; prefer ticketOptions and its field evidence."
          },
          "ticketOffer": {
            "type": "object",
            "required": [
              "price",
              "priceCurrency",
              "url"
            ],
            "properties": {
              "price": {
                "type": "number"
              },
              "priceCurrency": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "validFrom": {
                "type": "string",
                "format": "date-time"
              },
              "availability": {
                "type": "string",
                "enum": [
                  "InStock",
                  "SoldOut",
                  "PreOrder"
                ]
              }
            },
            "description": "Compatibility summary derived from canonical ticketOptions when those are present; prefer ticketOptions and its field evidence."
          },
          "regularTicket": {
            "type": "object",
            "description": "Compatibility summary derived from canonical ticketOptions when those are present; prefer ticketOptions and its field evidence.",
            "required": [
              "url",
              "reviewedOn",
              "date",
              "venue",
              "phases"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "reviewedOn": {
                "type": "string",
                "description": "Human-readable historical review date; not an ISO timestamp."
              },
              "date": {
                "type": "string",
                "format": "date"
              },
              "venue": {
                "type": "string"
              },
              "phases": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "name",
                    "price",
                    "serviceFee",
                    "conditions"
                  ],
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "price": {
                      "type": "number"
                    },
                    "serviceFee": {
                      "type": "number"
                    },
                    "conditions": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "ticketOptions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TicketOption"
            },
            "description": "Canonical price phases and The List offers with separate evidence for price, fees, conditions and availability."
          },
          "practicalFacts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "label",
                "text",
                "source"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "source": {
                  "$ref": "#/components/schemas/FactSource"
                }
              }
            }
          },
          "factSources": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/FactSource"
            }
          },
          "guestlist": {
            "type": "object",
            "description": "Derived from matched live The List group; source date checks the group link, not ticket prices or eligibility review. Not admission confirmation.",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "conditions": {
                "type": "string"
              },
              "source": {
                "$ref": "#/components/schemas/FactSource"
              }
            }
          },
          "enrichmentReview": {
            "type": "object",
            "properties": {
              "attemptedAt": {
                "type": "string"
              },
              "fieldsChecked": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "unresolved": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "failedSources": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "Location": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "club",
              "poppodium",
              "eventlocatie"
            ]
          },
          "description": {
            "type": "string"
          },
          "genres": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "officialUrl": {
            "type": "string",
            "format": "uri"
          },
          "agendaUrl": {
            "type": "string",
            "format": "uri"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "address": {
            "type": "object",
            "required": [
              "streetAddress",
              "addressCountry",
              "sourceUrl",
              "checkedAt"
            ],
            "properties": {
              "streetAddress": {
                "type": "string"
              },
              "postalCode": {
                "type": "string"
              },
              "addressCountry": {
                "type": "string"
              },
              "sourceUrl": {
                "type": "string",
                "format": "uri"
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "modifiedAt": {
            "type": "string",
            "format": "date-time"
          },
          "pageModifiedAt": {
            "type": "string",
            "format": "date-time"
          },
          "reviewedAt": {
            "type": "string",
            "format": "date-time"
          },
          "checkedAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastAttemptAt": {
            "type": "string",
            "format": "date-time"
          },
          "sourceError": {
            "type": "string"
          },
          "selectionReason": {
            "type": "string"
          },
          "upcomingEvents": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "date": {
                  "type": "string",
                  "format": "date"
                },
                "time": {
                  "type": "string"
                },
                "age": {
                  "type": "string"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "tickets",
                    "sold-out",
                    "tba"
                  ]
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "ticketUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "sourceUrl": {
                  "type": "string",
                  "format": "uri"
                },
                "checkedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "modifiedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "ticketOptions": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/TicketOption"
                  }
                },
                "guestlistAvailable": {
                  "type": "boolean"
                },
                "guestlistUrl": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "FactSource": {
        "type": "object",
        "required": [
          "url",
          "checkedAt",
          "role"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "checkedAt": {
            "type": "string",
            "description": "Actual observation timestamp, or YYYY-MM-DD when only a historical day was recorded; never refreshed by a general scrape."
          },
          "role": {
            "type": "string",
            "enum": [
              "organizer",
              "venue",
              "ticketshop",
              "thelist",
              "platform"
            ]
          },
          "publishedAt": {
            "type": "string",
            "description": "Actual source publication date/time, when explicitly known."
          }
        }
      },
      "TicketOption": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "name",
          "url",
          "currency",
          "evidence"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "regular",
              "thelist"
            ]
          },
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "currency": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "serviceFee": {
            "type": "number",
            "description": "Omitted when unknown; never assume zero."
          },
          "regularPrice": {
            "type": "number"
          },
          "conditions": {
            "type": "string"
          },
          "availability": {
            "type": "string",
            "enum": [
              "InStock",
              "SoldOut",
              "PreOrder"
            ]
          },
          "current": {
            "type": "boolean",
            "description": "Only supplied with evidence of actual current phase; not inferred from price."
          },
          "evidence": {
            "type": "object",
            "additionalProperties": {
              "$ref": "#/components/schemas/FactSource"
            }
          },
          "conflicts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Unresolved conflict; suppress numeric prices and schema offers."
          },
          "totalPrice": {
            "type": "number",
            "minimum": 0,
            "description": "Explicitly confirmed total including all mandatory costs. Does not invent a service-fee breakdown."
          },
          "additionalFees": {
            "type": "string",
            "description": "Additional mandatory variable or order-level costs; prevents a derived all-in total unless totalPrice is confirmed."
          }
        }
      }
    }
  }
}