openapi: 3.1.0
info:
  title: Howler API v3 Artists Events API
  version: 3.6.1
  description: '*Last updated: 2026-01-20 21:15:49 +0200*

    '
servers:
- url: https://{defaultHost}/api/v3/consumer_portal
  variables:
    defaultHost:
      default: www.howler.co.za
  description: Server for consumer portal endpoints
security:
- bearer_header: []
  bearer_param: []
  api_key: []
  bearer_auth: []
tags:
- name: Events
paths:
  /events/{event_id}:
    parameters:
    - name: event_id
      in: path
      description: event_id
      required: true
      schema:
        type: integer
    get:
      summary: show never live event
      security:
      - api_key: {}
      operationId: getConsumerEvent
      tags:
      - Events
      description: 'Retrieve details of the specified event.

        '
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  event:
                    $ref: '#/components/schemas/Event'
  /events/{event_id}/performance/{performance_id}:
    parameters:
    - name: event_id
      in: path
      description: Event ID
      required: true
      schema:
        type: integer
    - name: performance_id
      in: path
      description: Performance ID
      required: true
      schema:
        type: integer
    post:
      summary: add performance to time table
      tags:
      - Events
      operationId: addPerformanceToTimeTable
      description: Add a performance to the time table for the current user.
      responses:
        '201':
          description: already added to time table
    delete:
      summary: remove performance from time table
      tags:
      - Events
      operationId: removePerformanceFromTimeTable
      description: Remove a performance from the time table for the current user.
      responses:
        '204':
          description: not added to time table
components:
  schemas:
    UserValidationConfiguration:
      type: object
      properties:
        require_id_number?:
          type: boolean
          description: South African ID number is required
        require_unique_identifier?:
          type: boolean
          description: ''
        require_first_name?:
          type: boolean
          description: First Name is required
        require_last_name?:
          type: boolean
          description: Last Name is required
        require_cellphone_number?:
          type: boolean
          description: Cellphone Number is required
        require_country?:
          type: boolean
          description: Country of Residence is required
        require_passport_country?:
          type: boolean
          description: Passport Country is required
        require_city?:
          type: boolean
          description: City of Residence is required
        require_gender?:
          type: boolean
          description: Gender is required
        require_date_of_birth?:
          type: boolean
          description: Date of Birth is required
        require_passport_number?:
          type: boolean
          description: Passport Number is required
        require_nickname?:
          type: boolean
          description: Nickname is required
        require_billing_address?:
          type: boolean
          description: Nilling Address is required
      required:
      - require_id_number?
      - require_unique_identifier?
      - require_first_name?
      - require_last_name?
      - require_cellphone_number?
      - require_country?
      - require_passport_country?
      - require_city?
      - require_gender?
      - require_date_of_birth?
      - require_passport_number?
      - require_nickname?
      - require_billing_address?
      description: Indicates which user details need to be completed before their profile is considered setup for an event.
    TicketType:
      type: object
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: ISO 8601
        updated_at:
          type: string
          format: ISO 8601
        name:
          type: string
        ticket_category:
          $ref: '#/components/schemas/TicketCategory'
          nullable: true
        cost:
          type: integer
        fee:
          type: integer
        booking_status:
          type: string
        virtual_credit_cents:
          type:
          - integer
          - 'null'
        description:
          type: string
        image_url:
          type:
          - string
          - 'null'
          description: URL to the ticket type image if attached
        topups_configuration:
          $ref: '#/components/schemas/TopupsConfiguration'
        customer_settings_configuration:
          $ref: '#/components/schemas/CustomerSettingsConfiguration'
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
          description: Questions associated with this ticket type
        hidden:
          type: boolean
        hidden_by_promo_code:
          type: boolean
      required:
      - id
      - updated_at
      - created_at
      - topups_configuration
    Question:
      type: object
      properties:
        id:
          type: integer
          description: Question ID
        text:
          type: string
          description: Question text
        required:
          type: boolean
          description: Whether the question is required
        question_type:
          type: string
          description: Type of question
          enum:
          - text
          - number
          - multiple_choice
          - multiple_answer
          - date
          - boolean
          - cellphone_number
          - id_number
        options:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Available options for multiple choice questions
        position:
          type: integer
          description: Display position of the question
      required:
      - id
      - text
      - required
      - question_type
    TopupsConfiguration:
      type: object
      properties:
        topups_enabled?:
          type: boolean
          description: Top Ups are enabled for the event
        prevent_topup_for_multiple_tickets_of_same_type?:
          type: boolean
          description: If a user own mutliple tickets of the same ticket type then they cannot bt topped up.
        small_topup_amount:
          type: integer
          description: Small Topup Amount
        medium_topup_amount:
          type: integer
          description: Medium Topup Amount
        large_topup_amount:
          type: integer
          description: Large Topup Amount
      required:
      - topups_enabled?
      - small_topup_amount
      - medium_topup_amount
      - large_topup_amount
    Venue:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Primary Key
        address:
          type: string
          description: Address
        external_identifier:
          type:
          - string
          - 'null'
          description: External Identifier
        latitude:
          type: string
          description: Latitude
        longitude:
          type: string
          description: Longitude
        name:
          type: string
          description: Name
        source:
          type:
          - string
          - 'null'
          description: Source
      required:
      - id
      - address
      - external_identifier
      - latitude
      - longitude
      - name
      - source
    TicketCategory:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        position:
          type: integer
        description:
          type: string
        created_at:
          type: string
          format: ISO 8601
        updated_at:
          type: string
          format: ISO 8601
      required:
      - id
      - name
      - position
      - created_at
      - updated_at
    CustomerSettingsConfiguration:
      type: object
      properties:
        customer_transfers_enabled?:
          type: boolean
          description: Ticket transfers are allowed
        require_signup_for_ticket_downloads?:
          type: boolean
          description: User profile must be setup, all required data capture completed and marketing questions answered before a user can download their tickets.
        ticket_downloads_enabled_at:
          type:
          - string
          - 'null'
          format: ISO 8601
          description: Specified date and time when tickets will be able to be downloaded.
        ticket_downloads_enabled?:
          type: boolean
          description: If true a user will be able to download their tickets at the specified date and time
        show_ticket_barcode?:
          type: boolean
          description: If tickets cannot be downloaded and this is true then the user will be able to see their barcode number of their ticket as text but not download or view it.
        sharing_required_enabled?:
          type: boolean
          description: Sharing required enabled.
      required: []
    Event:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: Name of the event
        ticket_types:
          type: array
          items:
            $ref: '#/components/schemas/TicketType'
          description: List of ticket types available for this event
        add_ons:
          type: array
          items:
            $ref: '#/components/schemas/TicketType'
          description: List of addon ticket types for the event
        status:
          type: string
          enum:
          - pending
          - active
          - cancelled
        start_time:
          type:
          - string
          - 'null'
          format: ISO 8601
        end_time:
          type:
          - string
          - 'null'
          format: ISO 8601
        currency:
          type: string
          description: ISO 4217 Currency Code
        cashouts_enabled_at:
          type:
          - string
          - 'null'
          format: ISO 8601
        cashouts_disabled_at:
          type:
          - string
          - 'null'
          format: ISO 8601
        auto_cashouts_enabled?:
          type: boolean
          description: Event supports auto cashouts
        claim_barcode_feature?:
          type: boolean
          description: Tickets can be claimed by topping them up.
        enable_live_topups?:
          type: boolean
          description: Topups are allowed during the event.
        slug:
          type: string
          description: 'URL slug used for the event. The url for the event can be generated as follows: https://{baseUrl}/events/{slug}'
        short_url:
          type:
          - string
          - 'null'
          description: 'Short URL slug used for the event. The url for the event can be generated as follows: https://{baseUrl}/{short_url}'
        classification:
          type: string
          enum:
          - howler
          - howler_ticketing
          - howler_cashless
          - foreign_ticketing
        venue:
          $ref: '#/components/schemas/Venue'
        artist_lineup:
          type: array
          items:
            $ref: '#/components/schemas/ArtistLineup'
          description: List of artists performing at the event
        my_artist_lineup:
          type: array
          items:
            $ref: '#/components/schemas/ArtistLineup'
          description: List of this user's performances for the event
        is_cashless?:
          type: boolean
        is_past_event?:
          type: boolean
        user_validation_configuration:
          $ref: '#/components/schemas/UserValidationConfiguration'
        onsite_top_up_available?:
          type: boolean
        cashless_deposit_cents:
          type: integer
        header_image_url:
          type:
          - string
          - 'null'
        live:
          type: boolean
        mapboxUrl:
          type:
          - string
          - 'null'
      required:
      - id
      - name
      - currency
      - auto_cashouts_enabled?
      - slug
      - enable_live_topups?
      - onsite_top_up_available?
      - header_image_url
      - is_past_event?
      - live
      - ticket_types
      - add_ons
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 authentication for third-party applications
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          scopes:
            public: Public scope
            login: Login scope
            ott: One-time token scope
    bearer_header:
      type: http
      scheme: bearer
      bearerFormat: oauth2
      in: header
    bearer_param:
      type: apiKey
      scheme: bearer
      bearerFormat: oauth2
      name: bearer_token
      in: query
    jwt_header:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from basic authentication login
    jwt_param:
      type: apiKey
      name: bearer_token
      in: query
      description: JWT token as query parameter (alternative to Authorization header)
    basic_auth:
      type: http
      scheme: basic
      description: Basic authentication with email and password
    api_key:
      type: apiKey
      name: x-auth-token
      in: header
      description: API key authentication
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token authentication