{"openapi":"3.1.0","info":{"title":"BOOM Stand-Up Bar API","version":"1.0.0","summary":"Cartelera pública de shows de stand up comedy de BOOM Stand-Up Bar.","description":"API pública de solo lectura de BOOM Stand-Up Bar (FreeTicket): próximos shows de stand up comedy en Colombia y México, ciudades con cartelera y ranking de asistencia. No requiere autenticación ni clave. Las respuestas se cachean una hora. Todas las rutas bajo /api responden JSON, también los errores.","contact":{"name":"BOOM Stand-Up Bar","email":"contacto@boomstandupbar.com","url":"https://boomstandupbar.com/contact"},"termsOfService":"https://boomstandupbar.com/legal/terminos-de-uso"},"externalDocs":{"description":"Guía para desarrolladores y agentes","url":"https://boomstandupbar.com/developers"},"servers":[{"url":"https://boomstandupbar.com"}],"tags":[{"name":"events","description":"Cartelera de shows"},{"name":"cities","description":"Ciudades con shows"},{"name":"community","description":"Ranking de miembros"},{"name":"agents","description":"Recursos en markdown para modelos de lenguaje"}],"paths":{"/api/public/events":{"get":{"operationId":"listPublicEvents","tags":["events"],"summary":"Próximos shows de stand up comedy","description":"Devuelve los shows activos con fecha futura, ordenados por fecha ascendente. Filtra por ciudad con el slug que devuelve listPublicCities. Úsalo para responder qué comedia en vivo hay en una ciudad o fecha y enlazar la URL del evento para comprar.","parameters":[{"name":"city","in":"query","required":false,"description":"Slug de la ciudad, por ejemplo bogota o medellin.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Máximo de eventos a devolver.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Lista de eventos.","content":{"application/json":{"schema":{"type":"object","required":["events","total"],"properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/PublicEvent"}},"total":{"type":"integer","description":"Total de eventos que cumplen el filtro, antes de aplicar limit."}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/public/cities":{"get":{"operationId":"listPublicCities","tags":["cities"],"summary":"Ciudades con shows próximos","description":"Ciudades que tienen al menos un show activo con fecha futura. El slug sirve para filtrar listPublicEvents y la URL apunta a la landing de la ciudad.","responses":{"200":{"description":"Lista de ciudades.","content":{"application/json":{"schema":{"type":"object","required":["cities"],"properties":{"cities":{"type":"array","items":{"$ref":"#/components/schemas/PublicCity"}}}}}}}}}},"/api/racha/top-users":{"get":{"operationId":"listTopUsers","tags":["community"],"summary":"Ranking de miembros por puntos de racha","description":"Miembros con más puntos de asistencia a shows, de mayor a menor. Datos públicos del leaderboard de la web.","parameters":[{"name":"limit","in":"query","required":false,"description":"Cantidad de usuarios.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Ranking.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TopUser"}}}}},"500":{"description":"Error al obtener el ranking.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","tags":["agents"],"summary":"Índice del sitio para modelos de lenguaje","description":"Archivo llms.txt (llmstxt.org): qué es BOOM Stand-Up Bar, cuándo usarlo, cartelera actual, ciudades, comediantes y enlaces. Se regenera cada hora.","responses":{"200":{"description":"Markdown.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/md/{path}":{"get":{"operationId":"getPageMarkdown","tags":["agents"],"summary":"Versión markdown de una página pública","description":"Equivale a pedir la página normal con Accept: text/markdown. Cubre la cartelera (/, /home), las landings de ciudad (/stand-up-comedy/{slug}), los eventos (/events/{slug}), /about, /contact y /developers. Una ruta inexistente devuelve 404 con cuerpo markdown y enlaces para recuperarse.","parameters":[{"name":"path","in":"path","required":true,"description":"Ruta de la página sin la barra inicial, por ejemplo stand-up-comedy/bogota.","schema":{"type":"string"}}],"responses":{"200":{"description":"Markdown de la página.","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"La página no existe. El cuerpo es markdown con enlaces a llms.txt, sitemap y cartelera.","content":{"text/markdown":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Código estable en snake_case.","examples":["not_found","invalid_parameter"]},"message":{"type":"string","description":"Qué pasó, en español."},"hint":{"type":"string","description":"Cómo resolverlo."},"docs":{"type":"string","format":"uri"}}}}},"PublicEvent":{"type":"object","required":["id","slug","title","date","location","tier","isLive","isSoldOut","country","comedians","imageUrl","url"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"date":{"type":"string","format":"date-time","description":"Inicio del show en UTC."},"location":{"type":"string","description":"Nombre del lugar."},"tier":{"type":"string","enum":["FREE","PREMIUM","EXCLUSIVE"],"description":"FREE: incluido en la membresía. PREMIUM y EXCLUSIVE: boleta o cupo aparte."},"isLive":{"type":"boolean","description":"Se transmite en streaming."},"isSoldOut":{"type":"boolean"},"city":{"type":["object","null"],"properties":{"name":{"type":"string"},"slug":{"type":"string"}}},"country":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"}}},"comedians":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri","description":"Página del evento para comprar o reservar."},"streamingUrl":{"type":["string","null"],"format":"uri"}}},"PublicCity":{"type":"object","required":["name","slug","url","eventsUrl"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"},"eventsUrl":{"type":"string","format":"uri"}}},"TopUser":{"type":"object","required":["id","rank","name","points","starRating"],"properties":{"id":{"type":"string"},"rank":{"type":"integer"},"name":{"type":"string"},"image":{"type":["string","null"],"format":"uri"},"points":{"type":"integer"},"starRating":{"type":"integer","minimum":0,"maximum":5}}}}}}