openapi: 3.0.3
info:
  title: Bookings VenueAPI
  version: 4.10.0
  contact:
    name: Bookable
    url: https://www.bookabletech.com
    email: hello@bookabletech.com
  description: >
    Bookings VenueAPI is a RESTful, OpenAPI-based interface that enables
    seamless, standardized booking operations across diverse venue management
    systems (RMS). 


    Designed for maximum interoperability, the API allows platforms to search,
    discover, and book venues regardless of the underlying technology stack. 


    Key capabilities include:

    - Retrieving venue data and availability in real-time

    - Creating bookings through a unified interface

    - Supporting both direct bookings and inquiry-based workflows

    - Enabling venues and distributors to discover each other via a dynamic,
    service-driven marketplace


    The API supports RBAC-secured OAuth2 to ensure role-based access control and
    secure data transactions. Built for SaaS environments, this service offers
    scalable, multi-tenant integrations for distribution platforms, booking
    engines, and RMS providers.
servers:
  - url: https://api-staging.bookabletech.com
    description: Staging
  - url: https://api.bookabletech.com
    description: Production
tags:
  - name: Venue
    description: Information about venue
  - name: Booking
    description: Information about the booking
paths:
  /venues:
    get:
      operationId: getVenues
      summary: Retrieve a list of venues
      description: >
        Returns a paginated list of venues available to the authenticated user
        or system.  This endpoint supports page-based pagination to efficiently
        retrieve large sets of results.
      tags:
        - Venue
      parameters:
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
        - name: venueName
          in: query
          required: false
          description: >
            Filter venues by name. Supports partial matching (case-insensitive).
            Example: "dishoom" will match "Dishoom Covent Garden".
          schema:
            type: string
            minLength: 2
            maxLength: 100
          example: dishoom
        - name: venueGroupName
          in: query
          required: false
          description: >
            Filter venues by group or chain name. Supports partial matching
            (case-insensitive). Example: "gordon ramsay" will match all Gordon
            Ramsay restaurants.
          schema:
            type: string
            minLength: 2
            maxLength: 100
          example: gordon ramsay
        - name: features
          in: query
          required: false
          description: >
            Filter venues by features. Supports multiple values separated by
            commas. Available features include: dog_friendly, wifi, parking,
            wheelchair_accessible,  tv_sports, live_music, karaoke, pool_table,
            romantic, casual, family_friendly,  quiet, lively, italian, asian,
            vegetarian, seafood, etc.
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 10
          style: form
          explode: false
          example:
            - dog_friendly
            - wifi
            - romantic
        - name: content
          in: query
          required: false
          description: >
            Filter venues by description content. Supports partial matching
            (case-insensitive). Searches within the venue's content/description
            field.
          schema:
            type: string
            minLength: 3
            maxLength: 200
          example: bombay cuisine
        - name: productName
          in: query
          required: false
          description: >
            Filter venues by product/experience name. Supports partial matching
            (case-insensitive). Searches within product names and experience
            names.
          schema:
            type: string
            minLength: 2
            maxLength: 100
          example: dining room
        - name: bookingDays
          in: query
          required: false
          description: >
            Filter venues by available booking days. Supports multiple values
            separated by commas. Use day names (monday, tuesday, wednesday,
            thursday, friday, saturday, sunday).
          schema:
            type: array
            items:
              $ref: '#/components/schemas/DayOfWeek'
            minItems: 1
            maxItems: 7
          style: form
          explode: false
          example:
            - monday
            - tuesday
            - friday
        - name: area
          in: query
          required: false
          description: >
            Filter venues by area/location. Supports partial matching
            (case-insensitive). Searches within the venue's area field.
          schema:
            type: string
            minLength: 2
            maxLength: 100
          example: covent garden
        - name: city
          in: query
          required: false
          description: |
            Filter venues by city. Supports partial matching (case-insensitive).
          schema:
            type: string
            minLength: 2
            maxLength: 100
          example: london
        - name: street
          in: query
          required: false
          description: >
            Filter venues by street address. Supports partial matching
            (case-insensitive). Searches within the venue's street address
            field.
          schema:
            type: string
            minLength: 3
            maxLength: 200
          example: upper st martin
        - name: venueTypes
          in: query
          required: false
          description: >
            Filter venues by type. Supports multiple values separated by commas.
            Available types include: restaurant, bar, cafe, hotel, pub, club,
            etc.
          schema:
            type: array
            items:
              type: string
            minItems: 1
            maxItems: 10
          style: form
          explode: false
          example:
            - restaurant
            - bar
        - name: date
          in: query
          required: false
          description: >
            Filter venues by booking rules for a specific date. Format: ISO 8601
            (YYYY-MM-DD). Returns venues that accept bookings on the specified
            date according to their booking rules. When both 'date' and
            'bookingDays' filters are provided,  the 'date' filter takes
            precedence and overrides the 'bookingDays' filter.
          schema:
            type: string
            format: date
          example: '2025-10-15'
        - name: time
          in: query
          required: false
          description: >
            Filter venues by booking rules at a specific time. Format: 24-hour
            (HH:MM). Returns venues that accept bookings at the specified time
            according to their booking rules.  Must be used in conjunction with
            the date parameter.
          schema:
            type: string
            format: time
            nullable: true
          example: '19:30'
        - name: pageNumber
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
            nullable: false
          description: The index of the page to return (default is 1).
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            nullable: false
          description: The number of items to return per page (default is 20, max is 100).
        - name: sortBy
          in: query
          required: false
          description: >
            The field to sort results by. Defaults to 'Default' (composite ID
            ordering).

            - **default**: Sort by composite ID (venue_group_id, rms_id,
            venue_id)

            - **name**: Sort venues alphabetically by name

            - **city**: Sort venues by city name, then by venue name

            - **area**: Sort venues by area, then by venue name

            - **venueGroup**: Sort venues by venue group name (requires
            venueGroupName filter)

            - **relevance**: Sort by semantic similarity using vector embeddings
            (requires at least one embedding filter: venueName, content, or
            features with semantic search enabled)
          schema:
            type: string
            enum:
              - default
              - name
              - city
              - area
              - venueGroup
              - relevance
            default: default
          example: Name
        - $ref: '#/components/parameters/SortDirection'
      responses:
        '200':
          description: A list of venues was successfully retrieved.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Page'
                  - $ref: '#/components/schemas/VenueResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue:read
        - Production:
            - venue:read
  /venues/{venueId}:
    get:
      operationId: getVenue
      summary: Get the venue
      description: Retrieve a list of venues.
      tags:
        - Venue
      parameters:
        - name: venueId
          in: path
          required: true
          schema:
            type: string
          description: |
            The id of venue
          example: 29|X9|275cc44dd2e2496fba44857c9257443a
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
      responses:
        '200':
          description: Schema for the response returned when retrieving a list of venues.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Venue'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue:read
        - Production:
            - venue:read
  /venues/{compositeId}/availability:
    get:
      operationId: checkVenueAvailability
      summary: Check venue availability
      tags:
        - Venue
      parameters:
        - name: compositeId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the venue or product.
        - name: AvailabilityRequest
          in: query
          schema:
            $ref: '#/components/schemas/AvailabilityRequest'
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
      responses:
        '200':
          description: Success response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue:read
        - Production:
            - venue:read
  /venues/{compositeId}/booking:
    post:
      operationId: createBooking
      summary: Create a new booking
      tags:
        - Venue
        - Booking
      parameters:
        - name: compositeId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the venue/product.
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
        - $ref: '#/components/parameters/IntegrationSlug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingRequest'
      responses:
        '201':
          description: Success created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue-booking:create
        - Production:
            - venue-booking:create
  /venues/bookings:
    get:
      summary: Retrieve a list of bookings
      description: Returns a paginated list of all bookings.
      operationId: getBookings
      parameters:
        - name: cursor
          in: query
          required: false
          description: >
            A pagination cursor indicating the starting point for the next set
            of results.  If not provided, the first page of results will be
            returned.
          schema:
            type: string
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
      tags:
        - Venue
        - Booking
      responses:
        '200':
          description: A list of bookings
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ReservationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue-booking:read
        - Production:
            - venue-booking:read
  /venues/bookings/{bookingId}:
    get:
      summary: Retrieve a booking by ID
      description: Returns a specific booking by its unique ID.
      operationId: getBookingById
      tags:
        - Venue
        - Booking
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the booking
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
      responses:
        '200':
          description: Reservation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue-booking:read
        - Production:
            - venue-booking:read
    put:
      operationId: updateBookingById
      summary: Update an existing booking by ID
      tags:
        - Venue
        - Booking
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
          description: The unique identifier of the booking.
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBookingRequest'
      responses:
        '200':
          description: Reservation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue-booking:update
        - Production:
            - venue-booking:update
    delete:
      operationId: deleteBookingById
      summary: Cancel a booking by ID
      tags:
        - Venue
        - Booking
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the booking
        - $ref: '#/components/parameters/PartnerReference'
        - $ref: '#/components/parameters/CorrelationID'
      responses:
        '204':
          description: Booking cancelled successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        default:
          $ref: '#/components/responses/ServerError'
      security:
        - Staging:
            - venue-booking:delete
        - Production:
            - venue-booking:delete
components:
  schemas:
    DayOfWeek:
      type: string
      enum:
        - sunday
        - monday
        - tuesday
        - wednesday
        - thursday
        - friday
        - saturday
      description: Day of the week for booking availability
    VenueResponse:
      type: object
      description: >-
        A paginated list of venues with a cursor for retrieving the next page of
        results.
      properties:
        data:
          type: array
          description: A list of venue records for the current page.
          items:
            $ref: '#/components/schemas/Venue'
    Venue:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the venue.
        name:
          type: string
          description: The name of the venue.
        content:
          type: string
          description: Description or additional content about the venue.
        phone_number:
          type: string
          description: The contact phone number of the venue.
        website:
          type: string
          format: uri
          description: The official website of the venue.
        reservable:
          type: boolean
          description: Indicates if the venue can be reserved.
        location:
          type: object
          description: The location details of the venue.
          $ref: '#/components/schemas/Location'
        types:
          type: array
          items:
            type: string
          description: A list of types that categorize the venue.
        photos:
          type: array
          items:
            type: string
          description: A collection of photo URLs representing the venue.
        is_active:
          type: boolean
          description: Indicates if the venue is currently active.
          deprecated: true
          default: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the venue was created.
          deprecated: true
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the venue was last updated.
        products:
          type: array
          description: List of products available at the venue.
          items:
            $ref: '#/components/schemas/Product'
        packages:
          type: array
          description: List of packages available at the venue.
          items:
            $ref: '#/components/schemas/Package'
        menus:
          type: array
          description: List of menus available at the venue.
          items:
            $ref: '#/components/schemas/Menu'
        opening_times:
          type: object
          description: >-
            Opening times for the venue, including weekly schedule and specific
            date overrides.
          additionalProperties:
            $ref: '#/components/schemas/OpeningTime'
          example:
            monday:
              status: true
              open: '10:00'
              close: '23:00'
              notes: ''
              private_hire: false
            tuesday:
              status: true
              open: '10:00'
              close: '23:00'
              notes: ''
              private_hire: false
            '2025-12-25':
              status: false
              open: ''
              close: ''
              notes: Closed for Christmas
      required:
        - id
        - name
    Product:
      type: object
      description: A product available at a venue.
      properties:
        compositeId:
          type: string
          description: >-
            Unique identifier of the venue/product, used by other services
            (availability, booking, amendment)..
        productName:
          type: string
          description: Name of the booking product.
        timeInterval:
          type: integer
          description: The valid time options per booking for this product.
        bookingRules:
          properties:
            monday:
              type: object
              $ref: '#/components/schemas/BookingRule'
            tuesday:
              type: object
              $ref: '#/components/schemas/BookingRule'
            wednesday:
              type: object
              $ref: '#/components/schemas/BookingRule'
            thursday:
              type: object
              $ref: '#/components/schemas/BookingRule'
            friday:
              type: object
              $ref: '#/components/schemas/BookingRule'
            saturday:
              type: object
              $ref: '#/components/schemas/BookingRule'
            sunday:
              type: object
              $ref: '#/components/schemas/BookingRule'
        bookingOverrides:
          type: array
          items:
            $ref: '#/components/schemas/BookingOverride'
        operatorAvailabilityRules:
          type: array
          description: List of operator availability rules for the product
          items:
            $ref: '#/components/schemas/OperatorAvailabilityRule'
      required:
        - compositeId
    BookingOverride:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Unique identifier for the booking override
          example: 5e33079d6e4fb3019d08d127
        date_from:
          type: string
          format: date
          description: Start date for the override rule (inclusive)
          example: '2020-04-10'
          nullable: true
        date_to:
          type: string
          format: date
          description: End date for the override rule (inclusive)
          example: '2020-04-10'
          nullable: true
        booking_available:
          type: boolean
          description: Whether bookings are available during this period
          example: true
          nullable: true
        bookings_from:
          type: string
          format: time
          pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
          description: Start time for accepting bookings (HH:mm format)
          example: '11:00'
          nullable: true
        bookings_to:
          type: string
          format: time
          pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
          description: End time for accepting bookings (HH:mm format)
          example: '15:00'
          nullable: true
        min_duration:
          type: integer
          format: int32
          description: Minimum booking duration in minutes
          example: 120
          nullable: true
          minimum: 0
        max_duration:
          type: integer
          format: int32
          description: Maximum booking duration in minutes
          example: 120
          nullable: true
          minimum: 0
        min_people:
          type: integer
          format: int32
          description: Minimum number of people allowed per booking
          example: 1
          nullable: true
          minimum: 1
        max_people:
          type: integer
          format: int32
          description: Maximum number of people allowed per booking
          example: 24
          nullable: true
          minimum: 1
        auto_confirm_max:
          type: integer
          format: int32
          description: Maximum number of people for automatic booking confirmation
          example: 14
          nullable: true
          minimum: 0
        booking_notes:
          type: string
          description: Special notes or conditions for bookings during this period
          example: >-
            £10 per person card authentication required to confirm your booking.
            Should you wish to cancel the booking, please let us know within 48
            hours of your reservation otherwise your card will be charged at £10
            per person.
          nullable: true
          maxLength: 2000
    RuleDataBase:
      type: object
      required:
        - ruleType
      properties:
        ruleType:
          $ref: '#/components/schemas/OperatorAvailabilityRuleType'
      discriminator:
        propertyName: ruleType
        mapping:
          date_range: '#/components/schemas/DateRangeRuleData'
          recurring: '#/components/schemas/RecurringRuleData'
          time_based: '#/components/schemas/TimeBasedRuleData'
          specific_dates: '#/components/schemas/SpecificDatesRuleData'
    OperatorAvailabilityRule:
      type: object
      description: >-
        Represents an operator availability rule for managing booking
        availability
      required:
        - name
        - ruleType
        - ruleData
      properties:
        name:
          type: string
          description: Name of the availability rule
          example: Weekend Availability Rule
        description:
          type: string
          description: Description of the availability rule
          example: Rule that manages availability during weekends
          nullable: true
        ruleType:
          $ref: '#/components/schemas/OperatorAvailabilityRuleType'
        ruleData:
          $ref: '#/components/schemas/RuleDataBase'
    OperatorAvailabilityRuleType:
      type: string
      enum:
        - date_range
        - recurring
        - time_based
        - specific_dates
      description: >
        Type of availability rule:

        - `date_range`: Rules that apply to a continuous date range

        - `recurring`: Rules that repeat based on patterns (days of week,
        months)

        - `time_based`: Rules that apply to specific time periods within a day

        - `specific_dates`: Rules that apply to explicitly listed dates
      example: date_range
    DateRangeRuleData:
      allOf:
        - $ref: '#/components/schemas/RuleDataBase'
        - type: object
          description: Rule data for date range based availability rules
          required:
            - startDate
            - endDate
          properties:
            startDate:
              type: string
              format: date
              description: Start date of the date range (inclusive)
              example: '2025-11-01'
            endDate:
              type: string
              format: date
              description: End date of the date range (inclusive)
              example: '2025-11-04'
    RecurringRuleData:
      allOf:
        - $ref: '#/components/schemas/RuleDataBase'
        - type: object
          description: Rule data for recurring availability rules based on patterns
          required:
            - daysOfWeek
            - months
          properties:
            daysOfWeek:
              type: array
              items:
                type: integer
                minimum: 0
                maximum: 6
              description: >
                Days of the week when the rule applies (0=Sunday, 1=Monday, ...,
                6=Saturday).

                Multiple days can be specified for rules that apply to several
                days.
              example:
                - 0
                - 5
              minItems: 1
              maxItems: 7
            months:
              type: array
              items:
                type: integer
                minimum: 1
                maximum: 12
              description: >
                Months when the rule applies (1=January, 2=February, ...,
                12=December).

                Multiple months can be specified for rules that apply across
                multiple months.
              example:
                - 1
                - 2
              minItems: 1
              maxItems: 12
    TimeBasedRuleData:
      allOf:
        - $ref: '#/components/schemas/RuleDataBase'
        - type: object
          description: Rule data for time-based availability rules within a day
          required:
            - startTime
            - endTime
          properties:
            startTime:
              type: string
              format: time
              pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
              description: Start time when the rule applies (HH:mm format, 24-hour)
              example: '20:51'
            endTime:
              type: string
              format: time
              pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
              description: End time when the rule applies (HH:mm format, 24-hour)
              example: '03:51'
    SpecificDatesRuleData:
      allOf:
        - $ref: '#/components/schemas/RuleDataBase'
        - type: object
          description: Rule data for availability rules that apply to specific dates
          required:
            - dates
          properties:
            dates:
              type: array
              items:
                type: string
                format: date
              description: >
                List of specific dates when the rule applies (YYYY-MM-DD
                format).

                Each date in the array represents a day when this availability
                rule is active.
              example:
                - '2025-11-03'
                - '2025-11-05'
                - '2025-11-06'
              minItems: 1
    Location:
      type: object
      properties:
        area:
          type: string
          description: >-
            The general area where the venue is located Can be more than one
            separated by |.
        city:
          type: string
          description: The city where the venue is located.
        lat:
          type: number
          format: float
          description: The latitude coordinate of the venue.
        lng:
          type: number
          format: float
          description: The longitude coordinate of the venue.
        street:
          type: string
          description: The street address of the venue.
        postCode:
          type: string
          description: The postal code of the venue.
        gPlace:
          type: string
          description: The Google Place ID associated with the venue.
    BookingRule:
      type: object
      nullable: true
      description: Booking rule information.
      properties:
        from:
          type: string
          format: time
          nullable: true
          description: Starting time for which bookings are allowed (ISO8601 hh:mm format).
        to:
          type: string
          format: time
          nullable: true
          description: Ending time for which bookings are allowed (ISO8601 hh:mm format).
        bookingCutoff:
          type: string
          nullable: true
          description: >-
            The cutoff time after which bookings are no longer accepted. Accepts
            time in ISO 8601 `hh:mm` format or as a duration (e.g., `-60` for 2
            hours).
        minDuration:
          type: integer
          nullable: true
          description: The minimum duration in minutes allowed for the booking
        maxDuration:
          type: integer
          nullable: true
          description: The maximum duration in minutes allowed for the booking
        minPartySize:
          type: integer
          nullable: true
          description: The minimum partySize allowed for the booking
        maxPartySize:
          type: integer
          nullable: true
          description: The maximum partySize allowed for the booking
        notes:
          type: string
          nullable: true
          description: Optional notes or remarks for the booking.
    Package:
      type: object
      description: Represents a venue package/product
      properties:
        id:
          type: string
          description: Unique identifier for the package
          example: 5888a5afc71620e04002d5bb
        name:
          type: string
          description: Package name
          example: '*Pan roasted Padron peppers (V)'
        price:
          type: number
          format: float
          description: Package price
          example: 5.57
        description:
          type: string
          description: Detailed package description
          example: >-
            5 items per guest: Salmon & celeriac on rye, Buttermilk fries
            chicken...
        type:
          type: string
          description: Main package type
          example: food
        sub_type:
          type: string
          description: Package subtype (mainly for type=food)
          example: starter
        diet_types:
          type: array
          description: Supported diet types
          items:
            type: string
          example:
            - Vegetarian
            - Vegan
        allergens:
          type: array
          description: List of allergens present
          items:
            type: string
          example:
            - Gluten
            - Milk
        configurable_options:
          type: array
          description: Configurable options for the package
          items:
            $ref: '#/components/schemas/ConfigurableOption'
      required:
        - id
        - name
        - price
        - type
    ConfigurableOption:
      type: object
      description: Configurable option for a package
      properties:
        label:
          type: string
          description: Option label
          example: How Would You Like It Cooked ?
        description:
          type: string
          description: Option description
          example: Let us know how you like your steak cooked?
        min:
          type: integer
          description: Minimum number of selections required
          example: 1
        max:
          type: integer
          description: Maximum number of selections allowed
          example: 1
        values:
          type: array
          description: Available values for the option
          items:
            $ref: '#/components/schemas/ConfigurableValue'
    ConfigurableValue:
      type: object
      description: Configurable value of an option
      properties:
        label:
          type: string
          description: Value label
          example: Rare
        price_change:
          type: number
          format: float
          description: Price change for this value
          example: 2.5
        diet_types:
          type: array
          description: Diet types supported by this value
          items:
            type: string
          example:
            - Vegetarian
            - Vegan
        allergens:
          type: array
          description: Allergens added by this value
          items:
            type: string
          example:
            - Milk
        removes_allergens:
          type: array
          description: Allergens removed by this value
          items:
            type: string
          example:
            - Gluten
      required:
        - label
    Menu:
      type: object
      description: Represents a venue menu
      properties:
        id:
          type: string
          description: Unique identifier for the menu
          example: 68a5f2eee07ae30fcd653b03
        name:
          type: string
          description: Menu name
          example: Set Menu
        description:
          type: string
          description: Detailed menu description
          example: A choice of 2 or 3 courses from our set menu. Disclaimer:...
        items:
          type: array
          description: The available options for the menu
          items:
            $ref: '#/components/schemas/MenuItem'
      required:
        - id
        - name
        - items
    MenuItem:
      type: object
      description: Represents an option available for the menu
      properties:
        packageId:
          type: string
          description: The ID of the package that composes the menu item
          example: 62c6c9f532c7cc7e4265dfdc
        type:
          type: string
          description: The menu item type (e.g. food, drink, etc.)
          example: food
      required:
        - packageId
    OpeningTime:
      type: object
      description: Opening time information for a specific day or date.
      properties:
        status:
          type: boolean
          description: Whether the venue is open on this day/date.
          example: true
        open:
          type: string
          format: time
          pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
          description: Opening time in HH:mm format (e.g., "10:00").
          example: '10:00'
          nullable: true
        close:
          type: string
          format: time
          pattern: ^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$
          description: >-
            Closing time in HH:mm format (e.g., "23:00"). Can be "00:00" for
            midnight.
          example: '23:00'
          nullable: true
        notes:
          type: string
          description: Optional notes about the opening times.
          example: Happy hour until 19:00
          nullable: true
        private_hire:
          type: boolean
          description: Whether this is available for private hire only.
          example: false
          nullable: true
      required:
        - status
    AvailabilityRequest:
      type: object
      properties:
        partySize:
          type: integer
          description: The number of guests in the booking
          minimum: 1
        date:
          type: string
          format: date
          nullable: true
          description: The date for which availability is being checked (YYYY-MM-DD).
        startTime:
          type: string
          format: time
          nullable: true
          description: Preferred start time for the booking (HH:MM format)
        endTime:
          type: string
          format: time
          nullable: true
          default: '23:59'
          description: Desired end time of the booking (HH:MM format).
        duration:
          type: integer
          description: The duration of the booking in minutes
          nullable: true
      required:
        - partySize
        - date
        - startTime
    AvailabilityResponse:
      type: object
      properties:
        name:
          type: string
          description: The name of the available booking option.
        deposit:
          type: number
          format: float
          description: The deposit amount required for the booking.
        policy:
          type: string
          description: General policy details regarding the booking.
        cancellationPolicy:
          type: string
          description: Terms and conditions for canceling the booking.
        times:
          type: array
          items:
            type: object
            properties:
              time:
                type: string
                description: Available time slot for the booking (HH:MM format).
              duration:
                type: integer
                description: Duration of the booking in minutes.
              type:
                $ref: '#/components/schemas/AvailabilityType'
              productId:
                type: string
                description: >-
                  Unique identifier of the product (compositeId) that this time
                  slot refers to.
                nullable: true
        noAvailabilityAction:
          type: string
          description: >-
            Strategy provided by the RMS (Restaurant Management System) when no
            availability is found. Defines fallback actions or alternative
            options to present to customers.
        autoConfirmRule:
          $ref: '#/components/schemas/AutoConfirmRule'
          description: >-
            Configuration rule that determines when bookings should be
            automatically accepted without manual review.
    AutoConfirmRule:
      type: object
      description: >-
        Defines the criteria for automatically confirming bookings without
        manual intervention.
      properties:
        date:
          type: string
          format: date
          nullable: true
          description: >-
            Specific date when this rule applies (YYYY-MM-DD format). If null,
            rule applies based on other criteria.
        dateType:
          type: string
          nullable: true
          description: >-
            Type of date restriction (e.g., "date", "weekend", "special_event").
            Allows for categorized date-based rules.
        minPeople:
          type: integer
          nullable: true
          description: >-
            Minimum number of people required for auto-confirmation. If null, no
            minimum limit applies.
        maxPeople:
          type: integer
          nullable: true
          description: >-
            Maximum number of people allowed for auto-confirmation. If null, no
            maximum limit applies.
        timeFrom:
          type: string
          nullable: true
          format: time
          description: >-
            Start time for the auto-confirm window (HH:MM format). Bookings
            before this time won't be auto-confirmed.
        timeTo:
          type: string
          nullable: true
          format: time
          description: >-
            End time for the auto-confirm window (HH:MM format). Bookings after
            this time won't be auto-confirmed.
        weekdays:
          $ref: '#/components/schemas/VenueSearchWeekdays'
          nullable: true
          description: Specifies which days of the week this auto-confirm rule applies to.
    VenueSearchWeekdays:
      type: object
      description: Configuration object defining which weekdays a rule applies to.
      properties:
        monday:
          type: boolean
          nullable: true
          description: Whether the rule applies on Mondays.
        tuesday:
          type: boolean
          nullable: true
          description: Whether the rule applies on Tuesdays.
        wednesday:
          type: boolean
          nullable: true
          description: Whether the rule applies on Wednesdays.
        thursday:
          type: boolean
          nullable: true
          description: Whether the rule applies on Thursdays.
        friday:
          type: boolean
          nullable: true
          description: Whether the rule applies on Fridays.
        saturday:
          type: boolean
          nullable: true
          description: Whether the rule applies on Saturdays.
        sunday:
          type: boolean
          nullable: true
          description: Whether the rule applies on Sundays.
    AvailabilityType:
      description: >-
        Specifies how an operators time slot can be handled. A value of book
        indicates the slot is available for instant confirmation, while request
        means the slot requires manual approval through an enquiry-based
        process.
      type: string
      enum:
        - book
        - request
      example: request
    BookingRequest:
      type: object
      properties:
        firstName:
          type: string
          description: The first name for the booking.
          example: John
        lastName:
          type: string
          description: The last name for the booking.
          example: Doe
        partySize:
          type: integer
          description: The number of people the booking is for.
          minimum: 1
          example: 4
        date:
          type: string
          format: date
          nullable: true
          description: The date of the booking, in the format YYYY-MM-DD.
          example: '2025-02-15'
        time:
          type: string
          format: time
          nullable: true
          description: The time of the booking, in the format HH:mm.
          example: '18:30'
        type:
          $ref: '#/components/schemas/AvailabilityType'
        duration:
          type: integer
          nullable: true
          description: The duration of the booking in minutes.
          example: 90
        email:
          type: string
          format: email
          pattern: ^\S+@\S+\.\S+$
          description: The guest’s email address.
          example: john.doe@example.com
        phone:
          type: string
          description: The guest’s phone number.
          example: 1234567890
        notes:
          type: string
          nullable: true
          description: Any additional booking notes or special requests.
          example: Please prepare a birthday cake.
        adminNotes:
          type: array
          items:
            type: string
          nullable: true
          description: Internal notes or comments specific to the distributor.
        comments:
          type: array
          items:
            type: string
          nullable: true
          description: Additional comments or notes provided by the distributor.
        labels:
          type: array
          items:
            type: string
          nullable: true
          description: A list of labels or tags associated with the booking.
        preorders:
          type: array
          nullable: true
          description: a list of preorder packages associated with the booking.
          items:
            $ref: '#/components/schemas/PreorderRequest'
        preorderMenus:
          type: array
          nullable: true
          description: a list of preorder menus associated with the booking.
          items:
            $ref: '#/components/schemas/PreorderMenuRequest'
        partnerBookingId:
          type: string
          nullable: true
          description: >-
            Optional field that stores a reference code or unique identifier
            provided by an external system, used to link or synchronize records
            across platforms.
      required:
        - firstName
        - lastName
        - partySize
        - date
        - time
        - type
        - email
        - phone
    PreorderRequest:
      type: object
      properties:
        productId:
          type: string
          nullable: true
          description: >-
            The ID of the package associated with the pre-order. This field is
            deprecated, use packageId instead.
          example: 62692e90d2cf1f163744efc4
          deprecated: true
        packageId:
          type: string
          nullable: true
          description: The ID of the package associated with the pre-order.
          example: 62692e90d2cf1f163744efc4
        quantity:
          type: integer
          nullable: true
          description: The quantity of the product to be pre-ordered.
          default: 1
          example: 2
      required:
        - quantity
    PreorderMenuRequest:
      type: object
      properties:
        menuId:
          type: string
          nullable: false
          description: The ID of the menu to be added to the booking.
          example: 62692e90d2cf1f163744efc4
      required:
        - menuId
    UpdateBookingRequest:
      type: object
      properties:
        compositeId:
          type: string
          description: The unique identifier of the venue/product.
          example: >-
            29|X9|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0
        firstName:
          type: string
          description: The first name for the booking.
          example: John
        lastName:
          type: string
          description: The last name for the booking.
          example: Doe
        partySize:
          type: integer
          description: The number of people the booking is for.
          minimum: 1
          example: 4
        date:
          type: string
          format: date
          nullable: true
          description: The date of the booking, in the format YYYY-MM-DD.
          example: '2025-02-15'
        time:
          type: string
          format: time
          nullable: true
          description: The time of the booking, in the format HH:mm.
          example: '18:30'
        duration:
          type: integer
          description: The duration of the booking in minutes.
          nullable: true
          example: 120
        email:
          type: string
          format: email
          pattern: ^\S+@\S+\.\S+$
          description: The guest’s email address.
          example: john.doe@example.com
        phone:
          type: string
          description: The guest’s phone number.
          example: 1234567890
        notes:
          type: string
          nullable: true
          description: Any additional booking notes or special requests.
          example: Please prepare a birthday cake.
      required:
        - compositeId
        - firstName
        - lastName
        - partySize
        - date
        - time
        - email
        - phone
    BookingResponse:
      type: object
      properties:
        id:
          type: string
          example: 29|X9|275cc44dd2e2496fba44857c9257443a|B
    ReservationResponse:
      type: object
      title: Bookings
      description: A list of paginated bookings
      properties:
        data:
          title: Bookings
          description: The list of bookings
          type: array
          items:
            $ref: '#/components/schemas/Booking'
        cursor:
          type: string
          description: >
            A cursor that can be used to retrieve the next page of results.  If
            null or absent, there are no further pages.
    Booking:
      type: object
      title: Booking
      description: A detailed booking record.
      properties:
        id:
          type: string
          title: The Booking ID
          description: A globally unique identifier for the booking.
        compositeId:
          type: string
          title: The Composite ID
          description: A globally unique identifier for the venue/product.
        date:
          type: string
          format: date
          title: Reservation Date
          description: The date of the booking.
        time:
          type: string
          format: time
          title: Reservation Time
          description: The time of the booking.
        partySize:
          type: integer
          format: int32
          title: Party Size
          description: Number of guests for the booking.
        status:
          type: string
          title: Status
          description: >
            Indicates the current status of the booking:

            - `Pending`: The booking request has been received but not yet
            processed.

            - `InProgress`: The enquiry has been received and assigned but is
            not yet confirmed.

            - `Confirmed`: The booking has been confirmed.

            - `Cancelled`: The booking was cancelled or rejected.

            - `Deleted`: The booking has been deleted from the system.

            - `Lost`: The booking was not completed before its scheduled date.
          enum:
            - Pending
            - InProgress
            - Confirmed
            - Cancelled
            - Deleted
            - Lost
        reference:
          type: string
          title: Reference (deprecated)
          description: >
            Legacy reference code for the booking.  This field is deprecated and
            will be removed in future versions.  Please use `operatorBookingId`
            instead.
          deprecated: true
        firstName:
          type: string
          title: First Name
          description: Guest's first name.
        lastName:
          type: string
          title: Last Name
          description: Guest's last name.
        email:
          type: string
          format: email
          title: Email
          description: Email address of the guest.
        phone:
          type: string
          title: Phone
          description: Phone number of the guest.
        company:
          type: string
          title: Company
          description: Company name if the booking is business-related.
        location:
          $ref: '#/components/schemas/Location'
        duration:
          type: integer
          format: int32
          title: Duration
          description: Duration of the booking in minutes.
        productType:
          type: string
          title: Product Type
          description: Type of product or service reserved.
        notes:
          type: string
          title: Notes
          description: Additional notes for the booking.
        createdDate:
          type: string
          format: date-time
          title: Created Date
          description: Timestamp when the booking was created.
        lastUpdate:
          type: string
          format: date-time
          title: Last Updated
          description: Timestamp of the last booking update.
        preorders:
          type: array
          description: List of preordered packages for the booking.
          items:
            type: object
            properties:
              packageId:
                type: string
                description: Unique identifier for the preordered package.
              name:
                type: string
                description: Package name
                example: '*Pan roasted Padron peppers (V)'
              description:
                type: string
                description: Detailed package description
                example: >-
                  5 items per guest: Salmon & celeriac on rye, Buttermilk fries
                  chicken...
              type:
                type: string
                description: Main package type
                example: food
              quantity:
                type: integer
                description: Quantity of the preordered package.
              price:
                type: number
                format: float
                description: Package price
                example: 5.57
            required:
              - packageId
              - quantity
        preorderMenus:
          type: array
          description: List of preordered menus for the booking.
          items:
            type: object
            properties:
              menuId:
                type: string
                description: Unique identifier for the preordered menu.
            required:
              - menuId
        partnerBookingId:
          type: string
          title: Partner Booking Reference
          description: >
            A custom booking identifier provided by the distributor (partner). 
            This ID is submitted when creating a booking via API or Portal and 
            serves as the partner’s own reference code for cross-system
            tracking.
        operatorBookingId:
          type: string
          title: Operator Booking ID
          description: >
            The booking identifier generated by the operator’s RMS platform 
            (e.g., SevenRooms, Collins, Zonal). This ID uniquely identifies  the
            reservation within the operator’s system and is displayed in  the
            portal instead of the composite ID.
    Page:
      type: object
      properties:
        meta:
          type: object
          properties:
            totalItems:
              type: integer
              description: The total number of items available.
            totalPages:
              type: integer
              description: The total number of pages.
            currentPage:
              type: integer
              description: The current page number based on `limit` and `offset`.
            limit:
              type: integer
              description: The number of items returned per page.
    ClientError:
      description: Client error
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri
                description: >-
                  A URI reference [rfc9457] that identifies the problem type.
                  This specification encourages that, when dereferenced, it
                  provides human-readable documentation for the problem type
                  (e.g., using HTML [W3C.REC-html5-20141028]). When this member
                  is not present, its value is assumed to be "about:blank".
              title:
                type: string
                description: >-
                  A short, human-readable summary of the problem type. It SHOULD
                  NOT change from occurrence to occurrence of the problem,
                  except for purposes of localization.
              status:
                type: integer
                format: int32
                description: >-
                  The HTTP status code [rfc9457, Section 3.1.12] generated by
                  the origin server for this occurrence of the problem.
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem.
              instance:
                type: string
                format: uri
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem. It may or may not yield further information if
                  dereferenced.
            required:
              - title
              - status
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri
                description: >-
                  A URI reference [rfc9457] that identifies the problem type.
                  This specification encourages that, when dereferenced, it
                  provides human-readable documentation for the problem type
                  (e.g., using HTML [W3C.REC-html5-20141028]). When this member
                  is not present, its value is assumed to be "about:blank".
              title:
                type: string
                description: >-
                  A short, human-readable summary of the problem type. It SHOULD
                  NOT change from occurrence to occurrence of the problem,
                  except for purposes of localization.
              status:
                type: integer
                format: int32
                description: >-
                  The HTTP status code [rfc9457, Section 3.1.12] generated by
                  the origin server for this occurrence of the problem.
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem.
              instance:
                type: string
                format: uri
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem. It may or may not yield further information if
                  dereferenced.
            required:
              - title
              - status
  securitySchemes:
    Staging:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://bookabletech.uk.auth0.com/oauth/token
          scopes:
            venue:read: Grants read access to venue details
            venue-booking:read: Grants read access to venue bookings
            venue-booking:create: Grants permission to create venue bookings
            venue-booking:update: Grants permission to update venue bookings
            venue-booking:delete: Grants permission to delete venue bookings
            agent:write: Grants write access to bookable agents
      description: |
        This API uses OAuth2 client credentials flow via Auth0.
        **Important:** Include the `audience` parameter in your token request.
        Example token request:
        ```
        POST https://bookabletech.uk.auth0.com/oauth/token
        {
          "grant_type": "client_credentials",
          "client_id": "YOUR_CLIENT_ID",
          "client_secret": "YOUR_CLIENT_SECRET",
          "audience": "api.bookabletech.com"
        }
        ```
    Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.bookabletech.com/oauth/token
          scopes:
            venue:read: Grants read access to venue details
            venue-booking:read: Grants read access to venue bookings
            venue-booking:create: Grants permission to create venue bookings
            venue-booking:update: Grants permission to update venue bookings
            venue-booking:delete: Grants permission to delete venue bookings
            agent:write: Grants write access to bookable agents
      description: |
        This API uses OAuth2 client credentials flow via Auth0.
        **Important:** Include the `audience` parameter in your token request.
        Example token request:
        ```
        POST https://auth.bookabletech.com/oauth/token
        {
          "grant_type": "client_credentials",
          "client_id": "YOUR_CLIENT_ID",
          "client_secret": "YOUR_CLIENT_SECRET",
          "audience": "api.bookabletech.com"
        }
        ```
  parameters:
    CorrelationID:
      in: header
      name: X-Correlation-ID
      required: false
      description: >
        An optional ID which you can use to track transactions across multiple
        systems. It can have any value, but we recommend avoiding `.`
        characters.

        Mirrored back in a response header.
      schema:
        type: string
        example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA
    PartnerReference:
      in: header
      name: X-Partner-Reference
      required: false
      description: >
        Required for Bookable Agents. Specifies the partner reference for whom
        the booking is being made.

        This header must contain a valid partner reference when making requests
        with the `agent:write` scope.
      schema:
        type: string
        example: bottomlessbrunch.com
    IntegrationSlug:
      in: header
      name: X-Booking-Source
      required: false
      description: >
        Identifies the source or channel through which the booking was created.
        Valid values include:

        - "email" - Booking created via email integration

        - "phone" - Booking created via phone integration

        - "api" - Booking created via API (default if not provided)

        - "webhook" - Booking created via webhook integration

        - "js-tag" - Booking created via JavaScript tag integration

        - "chatbot" - Booking created via chatbot integration

        - "puller" - Booking created via puller synchronization

        - "portal" - Booking created via portal integration


        If not provided, defaults to "api" in the application logic.
      schema:
        type: string
        enum:
          - email
          - phone
          - api
          - webhook
          - js-tag
          - chatbot
          - puller
          - portal
        example: api
    SortDirection:
      in: query
      name: sortDirection
      required: false
      description: >
        The direction to sort results. Defaults to 'ASC'.

        - **ASC**: Ascending order (A-Z, 0-9, most similar to least similar for
        relevance)

        - **DESC**: Descending order (Z-A, 9-0, least similar to most similar
        for relevance)
      schema:
        type: string
        enum:
          - ASC
          - DESC
        default: ASC
      example: ASC
  responses:
    ServerError:
      description: Server error
      content:
        application/json:
          schema:
            type: object
            properties:
              type:
                type: string
                format: uri
                description: >-
                  A URI reference [rfc9457] that identifies the problem type.
                  This specification encourages that, when dereferenced, it
                  provides human-readable documentation for the problem type
                  (e.g., using HTML [W3C.REC-html5-20141028]). When this member
                  is not present, its value is assumed to be "about:blank".
              title:
                type: string
                description: >-
                  A short, human-readable summary of the problem type. It SHOULD
                  NOT change from occurrence to occurrence of the problem,
                  except for purposes of localization.
              status:
                type: integer
                format: int32
                description: >-
                  The HTTP status code [rfc9457, Section 3.1.12] generated by
                  the origin server for this occurrence of the problem.
              detail:
                type: string
                description: >-
                  A human-readable explanation specific to this occurrence of
                  the problem.
              instance:
                type: string
                format: uri
                description: >-
                  A URI reference that identifies the specific occurrence of the
                  problem. It may or may not yield further information if
                  dereferenced.
            required:
              - title
              - status
    BadRequest:
      description: Bad Request - The request was invalid or cannot be served
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientError'
          example:
            type: https://api.bookabletech.com/problems/bad-request
            title: Bad Request
            status: 400
            detail: The request contains invalid parameters
    Unauthorized:
      description: Unauthorized - Authentication is required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientError'
          example:
            type: https://api.bookabletech.com/problems/unauthorized
            title: Unauthorized
            status: 401
            detail: Authentication credentials are missing or invalid
    Forbidden:
      description: Forbidden - The request is understood but access is denied
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientError'
          example:
            type: https://api.bookabletech.com/problems/forbidden
            title: Forbidden
            status: 403
            detail: You do not have permission to access this resource
    NotFound:
      description: Not Found - The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientError'
          example:
            type: https://api.bookabletech.com/problems/not-found
            title: Not Found
            status: 404
            detail: The requested resource was not found
    InternalServerError:
      description: Internal Server Error - An unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
          example:
            type: https://api.bookabletech.com/problems/internal-server-error
            title: Internal Server Error
            status: 500
            detail: An unexpected error occurred while processing the request
    ServiceUnavailable:
      description: Service Unavailable - The server is temporarily unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError'
          example:
            type: https://api.bookabletech.com/problems/service-unavailable
            title: Service Unavailable
            status: 503
            detail: The server is temporarily unavailable. Please try again later
    Conflict:
      description: Conflict - The request conflicts with the current state of the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientError'
          example:
            type: https://api.bookabletech.com/problems/conflict
            title: Conflict
            status: 409
            detail: The request conflicts with the current state of the resource
    UnprocessableEntity:
      description: >-
        Unprocessable Entity - The request is well-formed but contains semantic
        errors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientError'
          example:
            type: https://api.bookabletech.com/problems/unprocessable-entity
            title: Unprocessable Entity
            status: 422
            detail: The request is well-formed but contains semantic errors
    TooManyRequests:
      description: Too Many Requests - Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClientError'
          example:
            type: https://api.bookabletech.com/problems/too-many-requests
            title: Too Many Requests
            status: 429
            detail: Rate limit exceeded. Please try again later
