openapi: 3.0.1
info:
  title: LiteAPI (Nuitée) Hotel Booking API
  description: >-
    LiteAPI by Nuitée is a unified hotel-booking and distribution API. It
    provides static hotel content and reference data, real-time rates and
    availability, the prebook/book/retrieve/cancel reservation flow, and
    loyalty and voucher management over 2M+ properties. All requests are
    authenticated with an X-API-Key header; a free sandbox key is available.
  termsOfService: https://www.liteapi.travel/terms
  contact:
    name: LiteAPI Support
    url: https://docs.liteapi.travel
  version: '3.0'
servers:
  - url: https://api.liteapi.travel/v3.0
    description: LiteAPI v3.0 production and sandbox base URL (key selects environment)
security:
  - ApiKeyAuth: []
tags:
  - name: Hotel Data
    description: Static hotel content, reviews, and reference data.
  - name: Rates
    description: Real-time room rates and availability search.
  - name: Booking
    description: Prebook, book, retrieve, list, and cancel reservations.
  - name: Loyalty
    description: Loyalty program configuration, points, and vouchers.
paths:
  /data/hotels:
    get:
      operationId: getHotels
      tags:
        - Hotel Data
      summary: List hotels
      description: Retrieve a list of hotels filtered by country, city, coordinates, or place.
      parameters:
        - name: countryCode
          in: query
          schema:
            type: string
          description: ISO-2 country code.
        - name: cityName
          in: query
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of hotels.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelListResponse'
  /data/hotel:
    get:
      operationId: getHotelDetails
      tags:
        - Hotel Data
      summary: Get hotel details
      description: Retrieve comprehensive details about a specific hotel.
      parameters:
        - name: hotelId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Hotel detail object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelDetailResponse'
  /data/reviews:
    get:
      operationId: getHotelReviews
      tags:
        - Hotel Data
      summary: Get hotel reviews
      description: Fetch guest reviews for a specific hotel.
      parameters:
        - name: hotelId
          in: query
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of reviews.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReviewsResponse'
  /data/countries:
    get:
      operationId: getCountries
      tags:
        - Hotel Data
      summary: List countries
      responses:
        '200':
          description: A list of countries with ISO-2 codes.
  /data/cities:
    get:
      operationId: getCities
      tags:
        - Hotel Data
      summary: List cities
      parameters:
        - name: countryCode
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of cities for the given country.
  /data/currencies:
    get:
      operationId: getCurrencies
      tags:
        - Hotel Data
      summary: List currencies
      responses:
        '200':
          description: A list of supported currencies.
  /data/iatacodes:
    get:
      operationId: getIataCodes
      tags:
        - Hotel Data
      summary: List IATA codes
      responses:
        '200':
          description: A list of IATA airport and city codes.
  /hotels/rates:
    post:
      operationId: searchRates
      tags:
        - Rates
      summary: Search hotel rates
      description: >-
        Search for real-time room rates and availability across multiple
        hotels by hotel IDs, city, coordinates, place, or IATA code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RatesSearchRequest'
      responses:
        '200':
          description: Rates and availability results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RatesSearchResponse'
  /rates/prebook:
    post:
      operationId: prebook
      tags:
        - Booking
      summary: Prebook a rate
      description: >-
        Initiate a prebooking session for a selected rate to lock the price
        and obtain a prebookId used to complete the booking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrebookRequest'
      responses:
        '200':
          description: Prebook session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrebookResponse'
  /rates/book:
    post:
      operationId: book
      tags:
        - Booking
      summary: Confirm a booking
      description: Confirm a booking using a prebookId, guest details, and payment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookRequest'
      responses:
        '200':
          description: Booking confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
  /bookings:
    get:
      operationId: listBookings
      tags:
        - Booking
      summary: List bookings
      description: Retrieve a list of all bookings, optionally filtered by date.
      responses:
        '200':
          description: A list of bookings.
  /bookings/{bookingId}:
    get:
      operationId: getBooking
      tags:
        - Booking
      summary: Retrieve a booking
      description: Get complete details for a specific booking.
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Booking detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
    put:
      operationId: cancelBooking
      tags:
        - Booking
      summary: Cancel a booking
      description: Cancel an existing booking by its identifier.
      parameters:
        - name: bookingId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Cancellation confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingResponse'
  /loyalties:
    get:
      operationId: getLoyalty
      tags:
        - Loyalty
      summary: Get loyalty settings
      description: Retrieve current loyalty program settings and cashback rates.
      responses:
        '200':
          description: Loyalty program settings.
    put:
      operationId: updateLoyalty
      tags:
        - Loyalty
      summary: Update loyalty settings
      description: Update loyalty program status and cashback rates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoyaltyRequest'
      responses:
        '200':
          description: Updated loyalty settings.
  /guests/{guestId}/bookings:
    get:
      operationId: getGuestBookings
      tags:
        - Loyalty
      summary: Get guest bookings
      description: >-
        Retrieve a list of bookings for a specific guest, including points
        earned and cashback applied.
      parameters:
        - name: guestId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Guest booking history with loyalty details.
  /vouchers:
    get:
      operationId: listVouchers
      tags:
        - Loyalty
      summary: List vouchers
      responses:
        '200':
          description: A paginated list of vouchers.
    post:
      operationId: createVoucher
      tags:
        - Loyalty
      summary: Create a voucher
      description: Create a discount voucher.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoucherRequest'
      responses:
        '200':
          description: Created voucher.
  /vouchers/{voucherId}:
    get:
      operationId: getVoucher
      tags:
        - Loyalty
      summary: Retrieve a voucher
      parameters:
        - name: voucherId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Voucher detail.
    delete:
      operationId: deleteVoucher
      tags:
        - Loyalty
      summary: Delete a voucher
      parameters:
        - name: voucherId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Deletion confirmation.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        LiteAPI key passed in the X-API-Key request header. A free sandbox
        key is available; live keys are issued from the LiteAPI dashboard.
  schemas:
    HotelListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Hotel'
    Hotel:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        country:
          type: string
        city:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        starRating:
          type: number
    HotelDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Hotel'
    ReviewsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              rating:
                type: number
              text:
                type: string
              date:
                type: string
    RatesSearchRequest:
      type: object
      required:
        - checkin
        - checkout
        - occupancies
      properties:
        hotelIds:
          type: array
          items:
            type: string
        cityName:
          type: string
        countryCode:
          type: string
        latitude:
          type: number
        longitude:
          type: number
        iataCode:
          type: string
        placeId:
          type: string
        checkin:
          type: string
          format: date
        checkout:
          type: string
          format: date
        occupancies:
          type: array
          items:
            type: object
            properties:
              adults:
                type: integer
              children:
                type: array
                items:
                  type: integer
        currency:
          type: string
        guestNationality:
          type: string
        margin:
          type: number
          description: Percentage commission margin added to the net rate.
        refundableRatesOnly:
          type: boolean
    RatesSearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              hotelId:
                type: string
              roomTypes:
                type: array
                items:
                  type: object
    PrebookRequest:
      type: object
      required:
        - offerId
      properties:
        offerId:
          type: string
          description: The rate offer identifier returned by /hotels/rates.
        usePaymentSdk:
          type: boolean
    PrebookResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            prebookId:
              type: string
            transactionId:
              type: string
            price:
              type: number
            currency:
              type: string
    BookRequest:
      type: object
      required:
        - prebookId
        - holder
        - guests
      properties:
        prebookId:
          type: string
        holder:
          type: object
          properties:
            firstName:
              type: string
            lastName:
              type: string
            email:
              type: string
        guests:
          type: array
          items:
            type: object
            properties:
              firstName:
                type: string
              lastName:
                type: string
        payment:
          type: object
          properties:
            method:
              type: string
    BookingResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            bookingId:
              type: string
            status:
              type: string
            hotelConfirmationCode:
              type: string
            checkin:
              type: string
              format: date
            checkout:
              type: string
              format: date
            price:
              type: number
            currency:
              type: string
    LoyaltyRequest:
      type: object
      properties:
        status:
          type: string
          enum:
            - enabled
            - disabled
        cashbackRate:
          type: number
    VoucherRequest:
      type: object
      properties:
        voucherCode:
          type: string
        discountType:
          type: string
        discountValue:
          type: number
        currency:
          type: string
        validityStart:
          type: string
          format: date
        validityEnd:
          type: string
          format: date