Tickitto Events API

openapi: 3.0.1
info:
  title: Authentication Events API
  version: 1.0.0
tags:
- name: Events
paths:
  /api/events/:
    get:
      tags:
      - Events
      summary: Search For Events
      description: 'Retrieves events from the Tickitto inventory.


        The search endpoint is typically the first endpoint called to initiate an interaction with the Tickitto API and retrieves events within the date ranges specified.


        The Tickitto inventory is availability aware. Therefore, at the time of performing a search query, all events returned will have availability instances for the date range specified.


        If an event does not have any availability within the specified search date, it will not be returned in searches.


        The search endpoint supports text search as well as filters for different event categories, cities, countries, performers and more to create a powerful contextual search experience.


        The default timespan is 14 days.


        The endpoint supports pagination via the `skip` and `limit` parameters and the returned `X-Total-Count` header.'
      operationId: search_events
      security:
      - APIKeyHeader: []
      parameters:
      - name: t1
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: Start of the date range in which returned events should have availability. Defaults to today.
          examples:
          - '2027-01-17'
          title: T1
        description: Start of the date range in which returned events should have availability. Defaults to today.
      - name: t2
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date
          - type: 'null'
          description: End of the date range in which returned events should have availability. Defaults to 14 days from now.
          examples:
          - '2027-07-21'
          title: T2
        description: End of the date range in which returned events should have availability. Defaults to 14 days from now.
      - name: category
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Category or categories to restrict query to.
          examples:
          - - Sports
            - Bus Tours
            - Attractions
            - Family-Friendly
          default: []
          title: Category
        description: Category or categories to restrict query to.
      - name: city
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: City or cities to restrict query to.
          examples:
          - - Berlin
            - Dubai
            - London
          default: []
          title: City
        description: City or cities to restrict query to.
      - name: state
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: State or states to restrict query to.
          examples:
          - - Virginia
            - California
            - Texas
          default: []
          title: State
        description: State or states to restrict query to.
      - name: region
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Region or regions to restrict the query to.
          examples:
          - - Derbyshire
            - Umm Al-Quwain
          default: []
          title: Region
        description: Region or regions to restrict the query to.
      - name: country
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Countries to restrict query to.
          examples:
          - - United Arab Emirates
            - United Kingdom
            - Germany
          default: []
          title: Country
        description: Countries to restrict query to.
      - name: country_code
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            minLength: 2
            maxLength: 2
            pattern: '[A-Z][A-Z]'
          description: Two-letter ISO country codes to restrict query to.
          examples:
          - - AE
            - GB
            - DE
          default: []
          title: Country Code
        description: Two-letter ISO country codes to restrict query to.
      - name: performer
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Performers to restrict query to.
          default: []
          title: Performer
        description: Performers to restrict query to.
      - name: venue
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
          description: Venues to restrict query to.
          default: []
          title: Venue
        description: Venues to restrict query to.
      - name: event_type
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/EventType'
          description: Event types to restrict the query to.
          default: []
          title: Event Type
        description: Event types to restrict the query to.
      - name: min_price
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            minimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          description: The minimum price to restrict the query to.
          title: Min Price
        description: The minimum price to restrict the query to.
      - name: max_price
        in: query
        required: false
        schema:
          anyOf:
          - type: number
            exclusiveMinimum: 0.0
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          description: The maximum price to restrict the query to.
          title: Max Price
        description: The maximum price to restrict the query to.
      - name: currency
        in: query
        required: false
        schema:
          type: string
          description: Currency to both display event prices and to restrict the min/max price query to.
          default: GBP
          title: Currency
        description: Currency to both display event prices and to restrict the min/max price query to.
      - name: text
        in: query
        required: false
        schema:
          type: string
          description: Text to perform a search of events with.
          examples:
          - marina dinner cruise
          default: ''
          title: Text
        description: Text to perform a search of events with.
      - name: range
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Maximum distance from the requested city or cities, in km.
          default: 0
          title: Range
        description: Maximum distance from the requested city or cities, in km.
      - name: skip
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 0
          - type: 'null'
          description: Number of results to skip for pagination; see also `limit` and the `X-Total-Count` response header.
          title: Skip
        description: Number of results to skip for pagination; see also `limit` and the `X-Total-Count` response header.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          exclusiveMinimum: 0
          description: Number of results to return for pagination; see also `skip` and the `X-Total-Count` response header.
          default: 100
          title: Limit
        description: Number of results to return for pagination; see also `skip` and the `X-Total-Count` response header.
      - name: partial_match
        in: query
        required: false
        schema:
          type: boolean
          description: Perform partial/substring text matching, includes fuzzy search (max 1 character change)
          default: false
          title: Partial Match
        description: Perform partial/substring text matching, includes fuzzy search (max 1 character change)
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - $ref: '#/components/schemas/ResultSort'
          - type: 'null'
          description: Sort order to use.If not specified, the default sort order is textual relevance if applicable, else geographical distance if applicable, else an arbitrary stable order.
          title: Sort By
        description: Sort order to use.If not specified, the default sort order is textual relevance if applicable, else geographical distance if applicable, else an arbitrary stable order.
      - name: event_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
          - type: 'null'
          description: List of event IDs to retrieve.
          examples:
          - - T849
            - T850
          title: Event Ids
        description: List of event IDs to retrieve.
      - name: should_raise
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Should Raise
      - name: profile_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Profile name
          title: Profile Name
        description: Profile name
      - name: hostname
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Associated hostname
          title: Hostname
        description: Associated hostname
      - name: accept-language
        in: header
        required: false
        schema:
          type: string
          default: en
          title: Accept-Language
      - name: origin
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Origin
      - required: false
        description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
        example: 123e4567-e89b-12d3-a456-426614174000
        schema:
          type: string
        name: X-Correlation-ID
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/APIEvent'
                title: Response Search Events
          headers:
            X-Total-Count:
              schema:
                type: integer
              description: The total number of events that exist for this query, ignoring pagination.
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
        '401':
          content:
            application/json:
              example:
                request_id: REQUEST123
                detail:
                - type: authentication_error.insufficient_permissions
                  msg: Invalid API key - this API key does not have the required permissions to access this resource
                  loc: []
                - type: authentication_error.invalid_key
                  msg: Invalid API key - this API key either does not exist or is invalid
                  loc: []
                - type: authentication_error.key_missing
                  msg: An API key is required to access this endpoint
                  loc: []
              schema:
                $ref: '#/components/schemas/ErrorBody'
          description: Unauthorized
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
        '404':
          content:
            application/json:
              example:
                request_id: REQUEST123
                detail:
                - type: event_error.event_not_found
                  msg: The requested event could not be found
                  loc: []
              schema:
                $ref: '#/components/schemas/ErrorBody'
          description: Not Found
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
  /api/events/{event_id}:
    get:
      tags:
      - Events
      summary: Get Event By Id
      description: This endpoint can be used to retrieve an event by its ID. You will need to pass the event_id as a URL parameter.
      operationId: get_event
      security:
      - APIKeyHeader: []
      parameters:
      - name: event_id
        in: path
        required: true
        schema:
          type: string
          title: Event Id
      - name: currency
        in: query
        required: false
        schema:
          type: string
          description: Currency to display event prices.
          default: GBP
          title: Currency
        description: Currency to display event prices.
      - name: should_raise
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Should Raise
      - name: profile_name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Profile name
          title: Profile Name
        description: Profile name
      - name: hostname
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Associated hostname
          title: Hostname
        description: Associated hostname
      - name: accept-language
        in: header
        required: false
        schema:
          type: string
          default: en
          title: Accept-Language
      - name: origin
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Origin
      - required: false
        description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
        example: 123e4567-e89b-12d3-a456-426614174000
        schema:
          type: string
        name: X-Correlation-ID
        in: header
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIEvent'
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
        '401':
          content:
            application/json:
              example:
                request_id: REQUEST123
                detail:
                - type: authentication_error.insufficient_permissions
                  msg: Invalid API key - this API key does not have the required permissions to access this resource
                  loc: []
                - type: authentication_error.invalid_key
                  msg: Invalid API key - this API key either does not exist or is invalid
                  loc: []
                - type: authentication_error.key_missing
                  msg: An API key is required to access this endpoint
                  loc: []
              schema:
                $ref: '#/components/schemas/ErrorBody'
          description: Unauthorized
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
        '404':
          content:
            application/json:
              example:
                request_id: REQUEST123
                detail:
                - type: event_error.event_not_found
                  msg: The requested event could not be found
                  loc: []
              schema:
                $ref: '#/components/schemas/ErrorBody'
          description: Not Found
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          headers:
            X-Request-ID:
              schema:
                type: string
                format: uuid
              description: Server-generated UUID corresponding to this specific response and its initiating request.
              example: 123e4567-e89b-12d3-a456-426614174000
            X-Correlation-ID:
              schema:
                type: string
                format: uuid
              description: Optional transaction reference provided by the client. Used to correlate API requests and responses with client flow in logs, errors etc.
              example: 123e4567-e89b-12d3-a456-426614174000
components:
  schemas:
    PersonalisationField:
      type: string
      enum:
      - prefix
      - first_name
      - last_name
      - phone_number
      - email
      - birthdate
      - house_number
      - street_name
      - postal_code
      - country_code
      - city
      - nationality
      title: PersonalisationField
    PersonalisationFieldConstraints:
      properties:
        regex:
          anyOf:
          - type: string
          - type: 'null'
          title: Regex
          description: The regular expression that the field input should validate against
      type: object
      title: PersonalisationFieldConstraints
    ResultSort:
      type: string
      enum:
      - price_asc
      - price_desc
      - popularity
      title: ResultSort
    EventType:
      type: string
      enum:
      - Standard
      - Cinema
      title: EventType
      description: 'Event type classification.


        - STANDARD: (Currently) All non-cinema events

        - CINEMA: All cinema experiences'
    APIPickupPoint:
      properties:
        latitude:
          type: number
          title: Latitude
          description: Latitude in degrees
          examples:
          - 1.23456789
        longitude:
          type: number
          title: Longitude
          description: Longitude in degrees
          examples:
          - 1.23456789
        id:
          type: string
          title: Id
          description: Machine identifier for this place
          default: ''
          examples:
          - '123'
        pickup_point_name:
          type: string
          title: Pickup Point Name
          description: Friendly pickup point name
          examples:
          - North Hotel
        pickup_point_address:
          type: string
          title: Pickup Point Address
          description: Street address of the pickup point
          examples:
          - ''
      type: object
      required:
      - latitude
      - longitude
      - pickup_point_name
      - pickup_point_address
      title: APIPickupPoint
    Price:
      properties:
        amount:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Amount
          description: Monetary value of this price in the given currency, with decimal point i.e. not integer format
          examples:
          - '3.99'
        currency:
          type: string
          maxLength: 3
          minLength: 3
          pattern: '[A-Z][A-Z][A-Z]'
          title: Currency
          description: ISO 4217 code for the currency in which the item's prices are sent
          examples:
          - GBP
      type: object
      required:
      - amount
      - currency
      title: Price
      description: Represents an absolute monetary value in a particular currency. Cannot be negative.
    APIEvent:
      properties:
        cancellation_policy_information:
          items:
            type: string
          type: array
          title: Cancellation Policy Information
          description: Cancellation and refund policy for the item itself.
          default: []
          examples:
          - - Attendees must cancel at least 3 days in advance.
            - 50% of total price refundable only.
        cancellation_policy:
          type: string
          title: Cancellation Policy
          description: (DEPRECATED) Cancellation policy for the item itself.
          deprecated: true
        delivery_methods:
          items:
            $ref: '#/components/schemas/DeliveryMethod'
          type: array
          uniqueItems: true
          title: Delivery Methods
          description: List of supported delivery methods.
          default: []
          examples:
          - - document
            - collection
            - external
            - eticket
            - print
        performers:
          anyOf:
          - items:
              $ref: '#/components/schemas/EventPerformer'
            type: array
          - type: 'null'
          title: Performers
          description: List of performers, sports teams or competitors involved in this event, if applicable.
          default: []
        popularity:
          anyOf:
          - type: number
            maximum: 5.0
            minimum: 1.0
          - type: 'null'
          title: Popularity
          description: Event's popularity with end users, out of 5.
          examples:
          - 4.5
        duration:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration
          description: Number of minutes an instance of this event typically lasts.
          examples:
          - 90
        event_type:
          $ref: '#/components/schemas/EventType'
          description: 'Type of event. (Note: standard currently refers to all non-cinema events.)'
          default: Standard
        tags:
          anyOf:
          - items:
              type: string
            type: array
            uniqueItems: true
          - type: 'null'
          title: Tags
          description: List of keywords for this event, used in search.
        is_tbd:
          $ref: '#/components/schemas/IsTbd'
          description: Whether the event date and/or time are to be determined.
          default:
            time: false
            date: false
        no_fulfilment:
          type: boolean
          title: No Fulfilment
          description: When true there should be no post-purchase fulfilment actions taken even if a ticket is present
          default: false
        images:
          items:
            $ref: '#/components/schemas/Image'
          type: array
          title: Images
          description: URLs of images which represent this event.
          default: []
          examples:
          - - desktop: https://placekitten.com/g/1000/1000
              mobile: https://placekitten.com/g/1000/1000
            - desktop: https://place-puppy.com/1000x1000
              thumbnail: https://place-puppy.com/1000x1000
        videos:
          items:
            type: string
          type: array
          title: Videos
          description: Links to videos that represent this event, such as trailers.
          default: []
        admission_type:
          $ref: '#/components/schemas/AdmissionType'
          description: Type which determines entrant admission process; see https://docs.tickitto.com/events/overview.
        cancellation_allowed:
          type: boolean
          title: Cancellation Allowed
          description: Whether the ticket buyer may cancel this event after purchase.
          default: false
        personalisations_required:
          anyOf:
          - $ref: '#/components/schemas/PersonalisationFields'
          - type: 'null'
          description: Fields required for ticket personalisation, if any,
          examples:
          - fields:
              country_code:
                regex: ^(AF|AX|AL|DZ|AS|AD|AO|AI|AQ|AG|AR|AM|AW|AU|AT|AZ|BS|BH|BD|BB|BY)$
              first_name: {}
              last_name: {}
              phone_number: {}
        delayed_fulfilment:
          type: boolean
          title: Delayed Fulfilment
          description: Whether or not this event has delayed voucher fulfilment.
          default: false
        venue_location:
          items:
            $ref: '#/components/schemas/APIEventVenue'
          type: array
          title: Venue Location
          description: List of locations where this event occurs.
          default: []
          examples:
          - - id: '123'
              latitude: 1.2345678
              longitude: 1.2345678
              venue_address: 1 Event Way, Bristol
              venue_name: Event Stadium
            - id: '321'
              latitude: 1.2345678
              longitude: 1.2345678
              venue_address: 2 Event Lane, Bristol
              venue_name: Event World
        event_id:
          type: string
          title: Event Id
          description: Unique identifier for this event.
          examples:
          - T123
        addon_required:
          type: boolean
          title: Addon Required
          description: Whether the ticket buyer must select addons to book this event.
          default: false
        addons:
          items:
            $ref: '#/components/schemas/Addon'
          type: array
          title: Addons
          description: List of available addons for this event
          default: []
        pickup_required:
          type: boolean
          title: Pickup Required
          description: Whether the ticket buyer must select a location to be picked up e.g. in a dune buggy or safari vehicle
          default: false
        booking_type:
          $ref: '#/components/schemas/BookingType'
          description: Type which determines booking process
          default: basket_booking
        from_price:
          $ref: '#/components/schemas/Price'
          description: Price of the cheapest ticket associated with this event.
          examples:
          - amount: 3.99
            currency: GBP
        soft_availability_t1:
          type: string
          format: date-time
          title: Soft Availability T1
          description: Beginning of the period for which this event is available to book
        soft_availability_t2:
          type: string
          format: date-time
          title: Soft Availability T2
          description: End of the period for which this event is available to book
        categories:
          items:
            anyOf:
            - type: string
            - type: 'null'
          type: array
          title: Categories
        city:
          anyOf:
          - type: string
          - type: 'null'
          title: City
          description: Name of the city in which the event takes place.
          examples:
          - Bristol
        region:
          anyOf:
          - type: string
          - type: 'null'
          title: Region
          description: Name of the region in which the event takes place.
          examples:
          - Derbyshire
        state:
          anyOf:
          - type: string
          - type: 'null'
          title: State
          description: Name of the state in which the event takes place, if applicable.
          examples:
          - Virginia
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: Name of the country in which the event takes place.
          examples:
          - United Kingdom
        country_code:
          anyOf:
          - type: string
            pattern: '[A-Z][A-Z]'
          - type: 'null'
          title: Country Code
          description: ISO 3166-1 alpha-2 code for the country in which the event takes place.
          examples:
          - GB
        title:
          type: string
          title: Title
          description: Human-readable/marketing name for this event.
          examples:
          - The Event
        slug:
          type: string
          title: Slug
          description: SEO slug constructed from the event id
          examples:
          - 

# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tickitto/refs/heads/main/openapi/tickitto-events-api-openapi.yml