{"openapi":"3.1.0","info":{"title":"Tickets.dev API","version":"1","description":"Live ticket listings, all-in prices and seat maps from Ticketmaster, StubHub, SeatGeek, Vivid Seats, TickPick, Gametime, Viagogo and more, in one schema. Use the API key tk_test_sandbox to try it: it returns fixed sample data and is never billed.","contact":{"url":"https://tickets.dev/docs"},"termsOfService":"https://tickets.dev/terms-of-service"},"externalDocs":{"url":"https://tickets.dev/docs"},"servers":[{"url":"https://api.tickets.dev"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string","description":"Machine-readable error code, e.g. invalid_key, marketplace_required, rate_limited."},"message":{"type":"string","description":"What went wrong, for people."},"outcome":{"type":"string","description":"How the request ended, e.g. rejected."},"retryable":{"type":"boolean","description":"Whether retrying the same request can succeed. 429 responses also send Retry-After."},"request_id":{"type":"string","description":"Quote this when contacting support."}}}}},"Listing":{"type":"object","properties":{"listingId":{"type":"string","description":"The marketplace's own id for the listing: compare it within one marketplace only."},"inventoryType":{"type":"string","description":"primary or resale."},"section":{"type":"string","description":"Section, as the marketplace names it. Matches data-section in the seat map SVG."},"row":{"type":"string","description":"Row label."},"seats":{"type":"string","description":"Comma-separated seat numbers, when the marketplace shows them."},"quantity":{"type":"number","description":"Seats available in this listing."},"sellableQuantities":{"type":"string","description":"Quantities a buyer can buy, e.g. \"2,4\". A listing of 3 selling as \"1,3\" cannot sell 2."},"ticketPrice":{"type":"number","description":"Face price per ticket, before fees."},"fee":{"type":"number","description":"Per-ticket fees. 0 where the marketplace shows only an all-in price."},"totalPrice":{"type":"number","description":"All-in price per ticket, excluding sales tax, with the same meaning on every marketplace."},"ticketType":{"type":"string","description":"Delivery or ticket type, as the marketplace shows it."},"group":{"type":"string","description":"The marketplace's zone or price level, e.g. 100 Level."},"listingNotes":{"type":"string","description":"Listing features, e.g. Clear view or Obstructed view."},"dealScore":{"type":"string","description":"The marketplace's own value score, as it shows it. Empty where it shows none."}}},"Stats":{"type":"object","properties":{"listingCount":{"type":"number","description":"Listings on the page."},"ticketCount":{"type":"number","description":"Tickets across all listings."},"getInPrice":{"type":"number","description":"Lowest all-in price per ticket. 0 when there are no listings."},"medianPrice":{"type":"number","description":"Median all-in price per ticket."},"avgPrice":{"type":"number","description":"Mean all-in price per ticket."},"maxPrice":{"type":"number","description":"Highest all-in price per ticket."}}},"Snapshot":{"type":"object","description":"One capture: every listing on one event page on one marketplace, at capturedAt.","properties":{"source":{"type":"string","description":"The marketplace, e.g. stubhub."},"eventId":{"type":"string","description":"The marketplace's own id for the event."},"eventName":{"type":"string","description":"Event title."},"performers":{"type":"array","items":{"type":"object"},"description":"Performers, as the marketplace lists them."},"venueId":{"type":"string","description":"The marketplace's own venue id."},"venueName":{"type":"string","description":"Venue name."},"venueAddress":{"type":"string","description":"Street address of the venue."},"venueCity":{"type":"string","description":"Venue city."},"venueState":{"type":"string","description":"Venue state or province."},"venueTimezone":{"type":"string","description":"Venue time zone, where the marketplace gives one."},"eventDateLocal":{"type":"string","description":"Event date and time, venue-local ISO 8601 with offset."},"eventDateUtc":{"type":"string","description":"The same moment in ISO 8601 UTC."},"sourceUrl":{"type":"string","description":"The event page the capture read."},"capturedAt":{"type":"string","description":"When the capture ran, ISO 8601 UTC."},"currency":{"type":"string","description":"ISO 4217 currency of every price in the snapshot."},"note":{"type":"string","description":"The marketplace's notice, e.g. sold out or canceled. An empty capture with no note may be a partial page."},"sectionLevelUrl":{"type":"string","description":"With includeVenueMaps: section map SVG; shapes carry the listings' section names."},"seatLevelUrl":{"type":"string","description":"With includeVenueMaps: seat or row level map SVG."},"stats":{"$ref":"#/components/schemas/Stats"},"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"venueLayout":{"type":"object","description":"Sections, rows and seats of the venue map, where available."}}},"EventSource":{"type":"object","properties":{"marketplace":{"type":"string","description":"Marketplace key, e.g. ticketmaster."},"eventId":{"type":"string","description":"The marketplace's own event id."},"url":{"type":"string","description":"The event page on that marketplace: pass it to /v1/capture."}}},"Event":{"type":"object","properties":{"id":{"type":"string","description":"Tickets.dev event id."},"name":{"type":"string","description":"Event name."},"eventDateLocal":{"type":"string","description":"Venue-local ISO 8601 with offset."},"eventDateUtc":{"type":"string","description":"ISO 8601 UTC."},"venue":{"type":"object","properties":{"name":{"type":"string","description":"Venue."},"city":{"type":"string","description":"City."},"state":{"type":"string","description":"State."},"country":{"type":"string","description":"Country."},"timezone":{"type":"string","description":"Time zone."}}},"performers":{"type":"array","items":{"type":"object"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/EventSource"}},"updatedAt":{"type":"string","description":"When the catalog last updated this event."}}},"EventsPage":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"page":{"type":"number","description":"Page number."},"pageSize":{"type":"number","description":"Results per page."},"total":{"type":"number","description":"Matching events."},"numberOfPages":{"type":"number","description":"Pages in total."},"hasMore":{"type":"boolean"}}},"Sources":{"type":"object","properties":{"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","description":"Marketplace key."},"hosts":{"type":"array","items":{"type":"string"},"description":"Hosts that route to it."},"searchable":{"type":"boolean","description":"Whether /v1/events covers it."}}}}}},"Health":{"type":"object","properties":{"ok":{"type":"boolean"},"service":{"type":"string","description":"Service name."},"db":{"type":"string","description":"Database status."}}}}},"paths":{"/v1/capture":{"get":{"operationId":"capture","summary":"Capture one event: every listing on it, in one response","description":"Capture one event: every listing on it, in one response. A live key spends one credit; tk_test_sandbox returns a fixture and is never billed.","x-billable":true,"security":[{"apiKey":[]}],"parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"A marketplace event page URL."},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Marketplace key, only needed when the URL's host doesn't say (see /v1/capture/sources)."},{"name":"includeVenueMaps","in":"query","required":false,"schema":{"type":"boolean"},"description":"true to also return the seat map SVGs."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"}}}},"4XX":{"description":"Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error. Retry only when error.retryable is true; 429 sends Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/capture/{source}":{"get":{"operationId":"captureFromSource","summary":"The same capture with the marketplace in the path, e.g","description":"The same capture with the marketplace in the path, e.g. /v1/capture/ticketmaster.","x-billable":true,"security":[{"apiKey":[]}],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string"},"description":"Marketplace key, e.g. ticketmaster."},{"name":"url","in":"query","required":true,"schema":{"type":"string"},"description":"A marketplace event page URL."},{"name":"includeVenueMaps","in":"query","required":false,"schema":{"type":"boolean"},"description":"true to also return the seat map SVGs."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Snapshot"}}}},"4XX":{"description":"Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error. Retry only when error.retryable is true; 429 sends Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/capture/sources":{"get":{"operationId":"listSources","summary":"The marketplaces you can capture, and the hosts that route to each","description":"The marketplaces you can capture, and the hosts that route to each. Never billable.","x-billable":false,"security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sources"}}}},"4XX":{"description":"Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error. Retry only when error.retryable is true; 429 sends Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/health":{"get":{"operationId":"health","summary":"Service status","description":"Service status. No key required.","x-billable":false,"security":[],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"4XX":{"description":"Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error. Retry only when error.retryable is true; 429 sends Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/events":{"get":{"operationId":"searchEvents","summary":"Ticket event discovery and matching: search the catalog by name, performer, venue, date, or marketplace URL","description":"Ticket event discovery and matching: search the catalog by name, performer, venue, date, or marketplace URL. Returns one unified event with every matched marketplace ID and URL. Never billed.","x-billable":false,"security":[{"apiKey":[]}],"parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Event name, performer, venue, or any marketplace event URL."},{"name":"source","in":"query","required":false,"schema":{"type":"string"},"description":"Marketplace key, only needed when the URL's host doesn't say (see /v1/capture/sources)."},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"Earliest event date, ISO 8601."},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"Latest event date, ISO 8601."},{"name":"eventId","in":"query","required":false,"schema":{"type":"string"},"description":"A Tickets.dev event id."},{"name":"prefix","in":"query","required":false,"schema":{"type":"string"},"description":"Name prefix, for autocomplete."},{"name":"page","in":"query","required":false,"schema":{"type":"string"},"description":"Page number, from 1."},{"name":"pageSize","in":"query","required":false,"schema":{"type":"string"},"description":"Results per page."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsPage"}}}},"4XX":{"description":"Request error, e.g. invalid_key (401), marketplace_required (400), rate_limited (429, with Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Error. Retry only when error.retryable is true; 429 sends Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}