{"openapi":"3.1.0","info":{"title":"VenuNite Data API","version":"1.0.0","description":"Live-events data for the United States — concerts, comedy, theater, festivals, sports,\nfood & drink and community events, at venues from arenas to neighbourhood breweries.\n\nAuthenticate with `Authorization: Bearer vn_live_...`. Generate a key yourself at\nhttps://venunite.com/developers/keys once you are on the developer plan — no need to email anyone.\n\nRate limit: 60 requests/minute per key. A 429 includes `Retry-After` in seconds.\n\nResults come from VenuNite's trusted serving view: active, de-duplicated,\nnon-cancelled, non-spam events at visible venues. Sold-out events are excluded.\n\nMeasured latency (2026-08-30, from a US client, includes network round-trip):\np50 ~180ms, p95 ~390ms. Served from us-west (AWS pdx1, Portland OR).\nThese are measurements, not an SLA.","contact":{"email":"hello@venunite.com","url":"https://venunite.com/developers/data-api"}},"servers":[{"url":"https://venunite.com","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An issued API key, e.g. `vn_live_...`."}},"schemas":{"Event":{"type":"object","required":["id","title","slug","startDate","categories"],"properties":{"id":{"type":"integer","examples":[654662]},"title":{"type":"string","examples":["PRCA Rodeo with Neal McCoy"]},"slug":{"type":"string","examples":["prca-rodeo-with-neal-mccoy"]},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":["string","null"],"format":"date-time"},"cost":{"type":["string","null"],"description":"Free-text as published by the source, e.g. \"$43.30\". Null when the source publishes no price — that is common and does NOT imply free admission (door cover, donation, pay-what-you-can, RSVP-only).","examples":["$43.30",null]},"age":{"type":["string","null"],"examples":["All Ages",null]},"ticketUrl":{"type":["string","null"],"description":"External ticketing URL. Null for non-ticketed events (community events, open mics, trivia) — not a data defect."},"imageUrl":{"type":["string","null"]},"categories":{"type":"array","items":{"type":"string"},"description":"Zero or more of a 21-category taxonomy, e.g. Music, Comedy, Sports, Food & Drink. May be empty.","examples":[["Sports"]]},"venue":{"type":["object","null"],"description":"Null on the rare event with no linked venue.","properties":{"id":{"type":"integer","examples":[282134]},"name":{"type":"string","examples":["Colorado State Fairgrounds"]},"city":{"type":"string","description":"Matched EXACTLY and case-sensitively by the `city` filter — pass \"Denver\", not \"denver\".","examples":["Pueblo"]},"state":{"type":"string","examples":["CO"]},"latitude":{"type":["number","null"],"examples":[38.2494]},"longitude":{"type":["number","null"],"examples":[-104.6346]}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_api_key","subscription_required","rate_limited","invalid_limit","invalid_date","invalid_date_range","invalid_cursor","invalid_state","internal_error"]},"message":{"type":"string"},"requestId":{"type":"string","description":"Also returned as the `x-request-id` header. Quote it in support email."}}}}}}},"paths":{"/v1/events":{"get":{"operationId":"listEvents","summary":"List upcoming events","description":"Events ordered by `startDate` ascending, then `id` ascending.\n\n**Pagination.** Pass `page.nextCursor` back as `cursor` to get the next page;\n`page.hasMore` is false on the last page. The cursor is an opaque keyset token over\n(startDate, id) — it will not skip or repeat events that share a start time, which a\ndate-offset approach does. Treat it as opaque; its encoding may change.\n\n**Window.** Every query is bounded. Without `starts_before` the window is\n`starts_after` + 90 days; a wider request is clamped to\n365 days. Page forward to walk further out.","parameters":[{"name":"state","in":"query","description":"Two-letter US state code, case-insensitive. Filters on the venue's state. An unrecognised code is a 400, not an empty result.","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"example":"CO"},{"name":"city","in":"query","description":"Exact venue city name, case-sensitive. Combine with `state` to disambiguate (there are many Springfields).","schema":{"type":"string"},"example":"Denver"},{"name":"starts_after","in":"query","description":"ISO 8601 date or date-time. Defaults to now.","schema":{"type":"string","format":"date-time"}},{"name":"starts_before","in":"query","description":"ISO 8601 date or date-time. Defaults to starts_after + 90 days; clamped to + 365 days.","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Events per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","description":"Opaque token from a previous response's `page.nextCursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of events.","headers":{"Cache-Control":{"description":"Always `private, no-store` — responses are per-key and must not be shared-cached.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","page"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"page":{"type":"object","required":["nextCursor","hasMore","count"],"properties":{"nextCursor":{"type":["string","null"]},"hasMore":{"type":"boolean"},"count":{"type":"integer"}}}}}}}},"400":{"description":"Invalid parameter. See `error.code`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_api_key","subscription_required","rate_limited","invalid_limit","invalid_date","invalid_date_range","invalid_cursor","invalid_state","internal_error"]},"message":{"type":"string"},"requestId":{"type":"string","description":"Also returned as the `x-request-id` header. Quote it in support email."}}}}}}}},"401":{"description":"Missing, malformed, unknown, or revoked API key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_api_key","subscription_required","rate_limited","invalid_limit","invalid_date","invalid_date_range","invalid_cursor","invalid_state","internal_error"]},"message":{"type":"string"},"requestId":{"type":"string","description":"Also returned as the `x-request-id` header. Quote it in support email."}}}}}}}},"402":{"description":"Valid key, but the account has no active developer plan — it lapsed, was cancelled, or was never started. Manage it at /developers/keys.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_api_key","subscription_required","rate_limited","invalid_limit","invalid_date","invalid_date_range","invalid_cursor","invalid_state","internal_error"]},"message":{"type":"string"},"requestId":{"type":"string","description":"Also returned as the `x-request-id` header. Quote it in support email."}}}}}}}},"429":{"description":"Rate limited. Retry after the `Retry-After` interval.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_api_key","subscription_required","rate_limited","invalid_limit","invalid_date","invalid_date_range","invalid_cursor","invalid_state","internal_error"]},"message":{"type":"string"},"requestId":{"type":"string","description":"Also returned as the `x-request-id` header. Quote it in support email."}}}}}}}},"500":{"description":"Unexpected server error. Safe to retry.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["invalid_api_key","subscription_required","rate_limited","invalid_limit","invalid_date","invalid_date_range","invalid_cursor","invalid_state","internal_error"]},"message":{"type":"string"},"requestId":{"type":"string","description":"Also returned as the `x-request-id` header. Quote it in support email."}}}}}}}}}}}}}