Tickitto Events API

openapi: 3.2.0
info:
  title: Authentication Events API
  version: 1.0.0
servers:
- url: https://tickitto.tech/api
  description: Base URL declared by the provider in apis.yml (roadmap#122).
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:
    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
    Addon:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
      type: object
      required:
      - id
      - name
      title: Addon
    PersonalisationFields:
      properties:
        fields:
          additionalProperties:
            $ref: '#/components/schemas/PersonalisationFieldConstraints'
          propertyNames:
            $ref: '#/components/schemas/PersonalisationField'
          type: object
          title: Fields
          description: A list of personalisations fields, included their regex-based constraints.
          default: {}
      type: object
      title: PersonalisationFields
    Image:
      properties:
        desktop:
          anyOf:
          - type: string
          - type: 'null'
          title: Desktop
          description: URL to use on desktop devices
        mobile:
          anyOf:
          - type: string
          - type: 'null'
          title: Mobile
          description: URL to use on mobile devices
        thumbnail:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail
          description: URL of a square version of this image
      type: object
      title: Image
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DeliveryMethod:
      type: string
      enum:
      - external
      - collection
      - document
      - eticket
      - print
      title: DeliveryMethod
    BookingType:
      type: string
      enum:
      - basket_booking
      - direct_booking
      title: BookingType
    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.
    AdmissionType:
      type: string
      enum:
      - open_entry
      - date_entry
      - slot_entry
      - timed_entry
      title: AdmissionType
    IsTbd:
      properties:
        time:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Time
          description: Whether the event time is to be determined
          default: false
        date:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Date
          description: Whether the event date is to be determined
          default: false
      type: object
      title: IsTbd
    ErrorBody:
      properties:
        request_id:
          type: string
          title: Request Id
        detail:
          items:
            $ref: '#/components/schemas/Error'
          type: array
          title: Detail
        body:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Body
      type: object
      required:
      - request_id
      - detail
      title: ErrorBody
    EventType:
      type: string
      enum:
      - Standard
      - Cinema
      title: EventType
      description: 'Event type classification.


        - STANDARD: (Currently) All non-cinema events

        - CINEMA: All cinema experiences'
    APIEventVenue:
      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'
        venue_brand_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Venue Brand Id
          description: The brand ID that operates the venue
        venue_address:
          type: string
          title: Venue Address
          description: Street address of the venue
          examples:
          - 27 Stadium Avenue
        seatplan_images:
          anyOf:
          - items:
              $ref: '#/components/schemas/Image'
            type: array
          - type: 'null'
          title: Seatplan Images
          description: Images of the venue's seatplan.
        configuration:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Configuration
        venue_name:
          type: string
          title: Venue Name
          description: Friendly venue name, in English
          examples:
          - Wembley Stadium
        venue_brand:
          anyOf:
          - type: string
          - type: 'null'
          title: Venue Brand
          description: The brand name that operates the venue
        venue_city:
          anyOf:
          - type: string
          - type: 'null'
          title: Venue City
          description: The city of the venue
          examples:
          - London
        venue_country:
          anyOf:
          - type: string
          - type: 'null'
          title: Venue Country
          description: The country of the venue
      type: object
      required:
      - latitude
      - longitude
      - venue_address
      - venue_name
      title: APIEventVenue
    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
    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'
          d

# --- 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