{"openapi":"3.1.0","info":{"title":"Upcoming API","version":"1.0.0","description":"Read-only access to everything public on Upcoming (https://upcoming-now.com): events, games, releases and the pages behind them. No key is needed. Lists hold 25 items at a time; follow next until it is null (a page can hold fewer items and still have a next). Up to 120 requests a minute from one address. Times are ISO 8601 in UTC with the event's own time zone alongside. Public data from Upcoming (https://upcoming-now.com). The facts are CC0 (public domain); descriptions Upcoming writes are CC BY 4.0. Please name Upcoming and link each item's url. Sports schedules from league feeds and TheSportsDB are not covered: don't redistribute them in bulk. https://upcoming-now.com/data","termsOfService":"https://upcoming-now.com/terms"},"servers":[{"url":"https://upcoming-now.com/api/v1"}],"externalDocs":{"description":"Guide for AI agents and crawlers","url":"https://upcoming-now.com/llms.txt"},"paths":{"/upcoming":{"get":{"operationId":"listUpcoming","summary":"What is coming up, soonest first","description":"Upcoming's public Explore list: events, releases and games on now or still to come, from pages Upcoming recommends.","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["Music","Technology","Food & drink","Arts & culture","Sports","Community"]},"description":"Only events in this category."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Where the previous page ended: its next_cursor. Cursors last a day."}],"responses":{"200":{"description":"A page of events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Send it back as If-None-Match to get 304 when nothing changed."},"Cache-Control":{"schema":{"type":"string"},"description":"Answers are kept for 60 seconds."}}},"400":{"description":"The request is not valid: a missing or too-long q, an unknown category, or a cursor that expired or was not given out here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing public on Upcoming matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 120 requests in a minute from one address. Wait for Retry-After seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Upcoming could not answer just now. Try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/search":{"get":{"operationId":"search","summary":"Search events or pages","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120},"description":"Words to look for. Matches names, descriptions, places, pages and what an event is about (rap finds a hip-hop show)."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["events","pages"],"default":"events"}},{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["Music","Technology","Food & drink","Arts & culture","Sports","Community"]},"description":"Only events in this category (type=events)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Where the previous page ended: its next_cursor. Cursors last a day."}],"responses":{"200":{"description":"Matching upcoming events (type=events) or pages (type=pages), best first.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EventList"},{"$ref":"#/components/schemas/PageList"}]}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Send it back as If-None-Match to get 304 when nothing changed."},"Cache-Control":{"schema":{"type":"string"},"description":"Answers are kept for 60 seconds."}}},"400":{"description":"The request is not valid: a missing or too-long q, an unknown category, or a cursor that expired or was not given out here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing public on Upcoming matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 120 requests in a minute from one address. Wait for Retry-After seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Upcoming could not answer just now. Try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"operationId":"getEvent","summary":"One event","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id in its url, /upcoming/{id}."}],"responses":{"200":{"description":"The event.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Event"},"notice":{"type":"string"}}}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Send it back as If-None-Match to get 304 when nothing changed."},"Cache-Control":{"schema":{"type":"string"},"description":"Answers are kept for 60 seconds."}}},"400":{"description":"The request is not valid: a missing or too-long q, an unknown category, or a cursor that expired or was not given out here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing public on Upcoming matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 120 requests in a minute from one address. Wait for Retry-After seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Upcoming could not answer just now. Try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{handle}":{"get":{"operationId":"getPage","summary":"One page: an organization, team, venue, league, artist or curator","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"},"description":"The handle in its url, /p/{handle}. The page id works too."}],"responses":{"200":{"description":"The page.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Page"},"notice":{"type":"string"}}}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Send it back as If-None-Match to get 304 when nothing changed."},"Cache-Control":{"schema":{"type":"string"},"description":"Answers are kept for 60 seconds."}}},"400":{"description":"The request is not valid: a missing or too-long q, an unknown category, or a cursor that expired or was not given out here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing public on Upcoming matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 120 requests in a minute from one address. Wait for Retry-After seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Upcoming could not answer just now. Try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pages/{handle}/events":{"get":{"operationId":"listPageEvents","summary":"What is coming up on one page","parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Where the previous page ended: its next_cursor. Cursors last a day."}],"responses":{"200":{"description":"The page and a page of its upcoming events.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EventList"},{"type":"object","properties":{"page":{"$ref":"#/components/schemas/PageRef"}}}]}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Send it back as If-None-Match to get 304 when nothing changed."},"Cache-Control":{"schema":{"type":"string"},"description":"Answers are kept for 60 seconds."}}},"400":{"description":"The request is not valid: a missing or too-long q, an unknown category, or a cursor that expired or was not given out here.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing public on Upcoming matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 120 requests in a minute from one address. Wait for Retry-After seconds.","headers":{"Retry-After":{"schema":{"type":"integer"}}}},"503":{"description":"Upcoming could not answer just now. Try again shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"PageRef":{"type":"object","required":["id","handle","name","url","api_url"],"properties":{"id":{"type":"string"},"handle":{"type":"string"},"name":{"type":"string"},"kind":{"type":["string","null"],"description":"organization, team, league, venue, person, series and so on."},"url":{"type":"string","format":"uri","description":"The page on Upcoming."},"api_url":{"type":"string","format":"uri"}}},"Page":{"allOf":[{"$ref":"#/components/schemas/PageRef"},{"type":"object","properties":{"category":{"type":["string","null"]},"description":{"type":["string","null"]},"website":{"type":["string","null"],"format":"uri"},"address":{"type":["string","null"],"description":"An organization's public address. Never given for a person."},"verified":{"type":"boolean","description":"Upcoming has verified who runs this page."},"curator":{"type":"boolean","description":"One of Upcoming's own curator pages, which recommend other pages' events."},"events_url":{"type":"string","format":"uri"}}}]},"Event":{"type":"object","required":["id","url","api_url","title"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri","description":"The event on Upcoming. Link it when you show the event."},"api_url":{"type":"string","format":"uri"},"title":{"type":"string"},"description":{"type":["string","null"]},"kind":{"type":["string","null"],"description":"event, release, window (a span of days) and so on."},"category":{"type":["string","null"]},"status":{"type":["string","null"],"description":"scheduled, canceled or postponed."},"tags":{"type":"array","items":{"type":"string"}},"date_precision":{"type":["string","null"],"enum":["time","date","tba",null],"description":"time: starts_at is exact. date: only the day is known (starts_on). tba: not announced yet."},"starts_at":{"type":["string","null"],"format":"date-time"},"ends_at":{"type":["string","null"],"format":"date-time"},"starts_on":{"type":["string","null"],"format":"date"},"ends_on":{"type":["string","null"],"format":"date"},"all_day":{"type":"boolean"},"timezone":{"type":["string","null"],"description":"IANA time zone the event happens in."},"location":{"type":["string","null"]},"link":{"type":["string","null"],"format":"uri","description":"The event's own link: tickets, a stream or more information."},"source_url":{"type":["string","null"],"format":"uri","description":"Where Upcoming learned about it."},"host":{"oneOf":[{"$ref":"#/components/schemas/PageRef"},{"type":"null"}],"description":"The page that posts it."},"pages":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PageRef"},{"type":"object","properties":{"roles":{"type":"array","items":{"type":"string"},"description":"host, co-host, competition, team, home_team, away_team, venue, performer…"}}}]}},"curated_by":{"type":"array","items":{"$ref":"#/components/schemas/PageRef"},"description":"Upcoming curator pages that recommend it."},"updated_at":{"type":["string","null"],"format":"date-time"}}},"EventList":{"type":"object","required":["data","next"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"next":{"type":["string","null"],"format":"uri","description":"The next page, or null at the end."},"next_cursor":{"type":["string","null"]},"notice":{"type":"string"}}},"PageList":{"type":"object","required":["data","next"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Page"}},"next":{"type":["string","null"],"format":"uri"},"next_cursor":{"type":["string","null"]},"notice":{"type":"string"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}