Tickets.dev Events API

openapi: 3.2.0
info:
  title: Tickets.dev Events 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
servers:
- url: https://api.tickets.dev
tags:
- name: Events
paths:
  /v1/events:
    get:
      operationId: searchEvents
      summary: 'Ticket event discovery and matching: search the catalog by name, performer…'
      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'
      tags:
      - Events
components:
  schemas:
    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
    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.
    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.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
externalDocs:
  url: https://tickets.dev/docs