openapi: 3.1.0
info:
  title: Airbnb Homes API
  description: >-
    The Airbnb Homes API provides approved connectivity partners with
    programmatic access to manage vacation rental listings on the Airbnb
    platform. It supports creating and updating property listings, managing
    descriptions, amenities, photos, pricing, and availability rules. The API
    also enables reservation management, calendar synchronization, guest
    messaging, and review handling. Access is restricted to approved
    connectivity partners such as property management systems and channel
    managers who integrate with Airbnb to help hosts manage their properties
    at scale.
  version: '2025.03.31'
  contact:
    name: Airbnb Developer Support
    url: https://developer.withairbnb.com/
  termsOfService: https://www.airbnb.com/terms
externalDocs:
  description: Airbnb Developer Documentation
  url: https://developer.withairbnb.com/
servers:
- url: https://api.airbnb.com/v2
  description: Airbnb Production API Server
tags:
- name: Calendar
  description: >-
    Operations for managing listing availability, pricing, and calendar
    synchronization across platforms.
- name: Listings
  description: >-
    Operations for creating, reading, updating, and managing property
    listings on Airbnb, including descriptions, amenities, and photos.
- name: Messages
  description: >-
    Operations for sending and retrieving guest and host messages within
    reservation threads.
- name: Photos
  description: >-
    Operations for uploading, updating, and managing listing photos.
- name: Reservations
  description: >-
    Operations for managing reservations, including accepting, declining,
    and retrieving booking details.
- name: Reviews
  description: >-
    Operations for retrieving and responding to guest and host reviews.
security:
- oauth2: []
paths:
  /listings:
    get:
      operationId: listListings
      summary: List All Listings
      description: >-
        Retrieves a paginated list of all property listings managed by the
        authenticated partner. Supports filtering by status and other
        listing attributes.
      tags:
      - Listings
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: status
        in: query
        description: >-
          Filter listings by their current status on the platform.
        schema:
          type: string
          enum:
          - active
          - inactive
          - pending
          - unlisted
      responses:
        '200':
          description: A paginated list of listings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  listings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Listing'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
        '403':
          description: The partner does not have permission to access listings.
    post:
      operationId: createListing
      summary: Create a New Listing
      description: >-
        Creates a new property listing on Airbnb with the provided details
        including property type, location, description, amenities, and
        house rules. The listing will be in a pending state until all
        required fields are completed and the listing is published.
      tags:
      - Listings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListingCreate'
      responses:
        '201':
          description: The listing was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing'
        '400':
          description: The request body contains invalid or missing fields.
        '401':
          description: Authentication credentials are missing or invalid.
  /listings/{listing_id}:
    get:
      operationId: getListing
      summary: Get a Listing
      description: >-
        Retrieves the full details of a specific property listing by its
        unique identifier, including description, amenities, photos,
        pricing, and availability configuration.
      tags:
      - Listings
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      responses:
        '200':
          description: The listing details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
    put:
      operationId: updateListing
      summary: Update a Listing
      description: >-
        Updates an existing property listing with the provided fields.
        Only the fields included in the request body will be modified.
        This can be used to update descriptions, amenities, house rules,
        and other listing attributes.
      tags:
      - Listings
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListingUpdate'
      responses:
        '200':
          description: The listing was successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Listing'
        '400':
          description: The request body contains invalid or missing fields.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
    delete:
      operationId: deleteListing
      summary: Delete a Listing
      description: >-
        Removes a property listing from the Airbnb platform. This action
        cannot be undone. Active reservations must be resolved before
        a listing can be deleted.
      tags:
      - Listings
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      responses:
        '204':
          description: The listing was successfully deleted.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
        '409':
          description: The listing has active reservations and cannot be deleted.
  /listings/{listing_id}/photos:
    get:
      operationId: listListingPhotos
      summary: List Listing Photos
      description: >-
        Retrieves all photos associated with a specific listing, including
        their captions, sort order, and dimensions.
      tags:
      - Photos
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      responses:
        '200':
          description: A list of photos for the listing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  photos:
                    type: array
                    items:
                      $ref: '#/components/schemas/Photo'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
    post:
      operationId: uploadListingPhoto
      summary: Upload a Listing Photo
      description: >-
        Uploads a new photo to a listing. Photos can include captions and
        a sort order to control display position in the listing gallery.
      tags:
      - Photos
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - photo
              properties:
                photo:
                  type: string
                  format: binary
                  description: >-
                    The photo file to upload.
                caption:
                  type: string
                  description: >-
                    An optional caption describing the photo.
                sort_order:
                  type: integer
                  description: >-
                    The display position of the photo in the listing gallery.
      responses:
        '201':
          description: The photo was successfully uploaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Photo'
        '400':
          description: The uploaded file is invalid or exceeds size limits.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
  /listings/{listing_id}/photos/{photo_id}:
    delete:
      operationId: deleteListingPhoto
      summary: Delete a Listing Photo
      description: >-
        Removes a specific photo from a listing by its identifier.
      tags:
      - Photos
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      - $ref: '#/components/parameters/photoIdParam'
      responses:
        '204':
          description: The photo was successfully deleted.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing or photo was not found.
  /listings/{listing_id}/calendar:
    get:
      operationId: getListingCalendar
      summary: Get Listing Calendar
      description: >-
        Retrieves the availability calendar for a specific listing over a
        date range. Returns day-by-day availability status, nightly pricing,
        minimum stay requirements, and any blocked dates.
      tags:
      - Calendar
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      - name: start_date
        in: query
        required: true
        description: >-
          The start date for the calendar range in ISO 8601 format.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        required: true
        description: >-
          The end date for the calendar range in ISO 8601 format.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: The calendar data for the specified date range.
          content:
            application/json:
              schema:
                type: object
                properties:
                  calendar_days:
                    type: array
                    items:
                      $ref: '#/components/schemas/CalendarDay'
        '400':
          description: The date range is invalid or missing.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
    put:
      operationId: updateListingCalendar
      summary: Update Listing Calendar
      description: >-
        Updates the availability, pricing, and minimum stay settings for
        specific dates on a listing calendar. Use this endpoint to block
        or unblock dates, adjust nightly pricing, and set minimum stay
        requirements.
      tags:
      - Calendar
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - calendar_operations
              properties:
                calendar_operations:
                  type: array
                  items:
                    $ref: '#/components/schemas/CalendarOperation'
      responses:
        '200':
          description: The calendar was successfully updated.
        '400':
          description: The request body contains invalid operations.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
  /reservations:
    get:
      operationId: listReservations
      summary: List Reservations
      description: >-
        Retrieves a paginated list of reservations for listings managed by
        the authenticated partner. Supports filtering by status, listing,
        and date range.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: status
        in: query
        description: >-
          Filter reservations by their current status.
        schema:
          type: string
          enum:
          - pending
          - accepted
          - denied
          - cancelled
          - checked_in
          - checked_out
      - name: listing_id
        in: query
        description: >-
          Filter reservations by listing identifier.
        schema:
          type: string
      - name: start_date
        in: query
        description: >-
          Filter reservations with check-in dates on or after this date.
        schema:
          type: string
          format: date
      - name: end_date
        in: query
        description: >-
          Filter reservations with check-in dates on or before this date.
        schema:
          type: string
          format: date
      responses:
        '200':
          description: A paginated list of reservations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reservations:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reservation'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
  /reservations/{reservation_id}:
    get:
      operationId: getReservation
      summary: Get a Reservation
      description: >-
        Retrieves the full details of a specific reservation including
        guest information, dates, pricing breakdown, and current status.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      responses:
        '200':
          description: The reservation details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
  /reservations/{reservation_id}/accept:
    post:
      operationId: acceptReservation
      summary: Accept a Reservation
      description: >-
        Accepts a pending reservation request. Once accepted, the
        reservation is confirmed and the calendar dates are blocked.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      responses:
        '200':
          description: The reservation was successfully accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
        '409':
          description: The reservation is not in a pending state.
  /reservations/{reservation_id}/deny:
    post:
      operationId: denyReservation
      summary: Deny a Reservation
      description: >-
        Denies a pending reservation request. A reason for denial may
        be provided to inform the guest.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: >-
                    The reason for denying the reservation request.
      responses:
        '200':
          description: The reservation was successfully denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
        '409':
          description: The reservation is not in a pending state.
  /reservations/{reservation_id}/cancel:
    post:
      operationId: cancelReservation
      summary: Cancel a Reservation
      description: >-
        Cancels an accepted reservation. Cancellation policies and fees
        may apply depending on the listing configuration and timing.
      tags:
      - Reservations
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: >-
                    The reason for cancelling the reservation.
      responses:
        '200':
          description: The reservation was successfully cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reservation'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
        '409':
          description: The reservation cannot be cancelled in its current state.
  /reservations/{reservation_id}/messages:
    get:
      operationId: listReservationMessages
      summary: List Reservation Messages
      description: >-
        Retrieves the message thread for a specific reservation, including
        all messages exchanged between the host and guest.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: A paginated list of messages in the reservation thread.
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
    post:
      operationId: sendReservationMessage
      summary: Send a Reservation Message
      description: >-
        Sends a new message in the reservation thread from the host to
        the guest. Messages are delivered through the Airbnb messaging
        system.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  type: string
                  description: >-
                    The text content of the message to send.
                  maxLength: 5000
      responses:
        '201':
          description: The message was successfully sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          description: The message content is invalid or exceeds length limits.
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
  /reservations/{reservation_id}/reviews:
    get:
      operationId: listReservationReviews
      summary: List Reservation Reviews
      description: >-
        Retrieves the reviews associated with a specific reservation,
        including both the guest review and host response if available.
      tags:
      - Reviews
      parameters:
      - $ref: '#/components/parameters/reservationIdParam'
      responses:
        '200':
          description: The reviews for the reservation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reviews:
                    type: array
                    items:
                      $ref: '#/components/schemas/Review'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The reservation was not found.
  /listings/{listing_id}/reviews:
    get:
      operationId: listListingReviews
      summary: List Listing Reviews
      description: >-
        Retrieves a paginated list of all reviews for a specific listing,
        including guest ratings and comments.
      tags:
      - Reviews
      parameters:
      - $ref: '#/components/parameters/listingIdParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      responses:
        '200':
          description: A paginated list of reviews for the listing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  reviews:
                    type: array
                    items:
                      $ref: '#/components/schemas/Review'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '401':
          description: Authentication credentials are missing or invalid.
        '404':
          description: The listing was not found.
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: >-
        Airbnb uses OAuth 2.0 for authentication. Partners must register
        their application to receive a client ID and secret, then obtain
        access tokens through the authorization code flow. Access tokens
        expire after 24 hours and must be refreshed.
      flows:
        authorizationCode:
          authorizationUrl: https://www.airbnb.com/oauth2/auth
          tokenUrl: https://api.airbnb.com/v2/oauth2/authorizations
          scopes:
            listings:read: Read listing information
            listings:write: Create and update listings
            reservations:read: Read reservation information
            reservations:write: Accept, deny, and cancel reservations
            messages:read: Read reservation messages
            messages:write: Send messages to guests
            reviews:read: Read reviews
            calendar:read: Read calendar availability
            calendar:write: Update calendar availability and pricing
  parameters:
    listingIdParam:
      name: listing_id
      in: path
      required: true
      description: >-
        The unique identifier of the listing.
      schema:
        type: string
    reservationIdParam:
      name: reservation_id
      in: path
      required: true
      description: >-
        The unique identifier of the reservation.
      schema:
        type: string
    photoIdParam:
      name: photo_id
      in: path
      required: true
      description: >-
        The unique identifier of the photo.
      schema:
        type: string
    limitParam:
      name: limit
      in: query
      description: >-
        The maximum number of results to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    offsetParam:
      name: offset
      in: query
      description: >-
        The number of results to skip for pagination.
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    Listing:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the listing.
        name:
          type: string
          description: >-
            The display name of the listing.
        description:
          type: string
          description: >-
            The full description of the property.
        property_type:
          type: string
          description: >-
            The type of property being listed.
          enum:
          - apartment
          - house
          - secondary_unit
          - unique_space
          - bed_and_breakfast
          - boutique_hotel
        room_type:
          type: string
          description: >-
            The type of room or space being offered.
          enum:
          - entire_home
          - private_room
          - shared_room
        status:
          type: string
          description: >-
            The current status of the listing on the platform.
          enum:
          - active
          - inactive
          - pending
          - unlisted
        address:
          $ref: '#/components/schemas/Address'
        bedrooms:
          type: integer
          description: >-
            The number of bedrooms in the property.
          minimum: 0
        bathrooms:
          type: number
          description: >-
            The number of bathrooms in the property.
          minimum: 0
        beds:
          type: integer
          description: >-
            The total number of beds in the property.
          minimum: 0
        max_guests:
          type: integer
          description: >-
            The maximum number of guests allowed.
          minimum: 1
        amenities:
          type: array
          description: >-
            The list of amenity identifiers available at the property.
          items:
            type: string
        house_rules:
          type: string
          description: >-
            The house rules and guidelines for guests.
        check_in_time:
          type: string
          description: >-
            The earliest check-in time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        check_out_time:
          type: string
          description: >-
            The latest check-out time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        pricing:
          $ref: '#/components/schemas/Pricing'
        photos:
          type: array
          description: >-
            The photos associated with the listing.
          items:
            $ref: '#/components/schemas/Photo'
        cancellation_policy:
          type: string
          description: >-
            The cancellation policy applied to the listing.
          enum:
          - flexible
          - moderate
          - strict
          - strict_14_with_grace_period
          - super_strict_30
          - super_strict_60
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the listing was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the listing was last updated.
    ListingCreate:
      type: object
      required:
      - name
      - property_type
      - room_type
      - address
      - max_guests
      properties:
        name:
          type: string
          description: >-
            The display name of the listing.
          maxLength: 50
        description:
          type: string
          description: >-
            The full description of the property.
          maxLength: 5000
        property_type:
          type: string
          description: >-
            The type of property being listed.
          enum:
          - apartment
          - house
          - secondary_unit
          - unique_space
          - bed_and_breakfast
          - boutique_hotel
        room_type:
          type: string
          description: >-
            The type of room or space being offered.
          enum:
          - entire_home
          - private_room
          - shared_room
        address:
          $ref: '#/components/schemas/Address'
        bedrooms:
          type: integer
          description: >-
            The number of bedrooms in the property.
          minimum: 0
        bathrooms:
          type: number
          description: >-
            The number of bathrooms in the property.
          minimum: 0
        beds:
          type: integer
          description: >-
            The total number of beds in the property.
          minimum: 0
        max_guests:
          type: integer
          description: >-
            The maximum number of guests allowed.
          minimum: 1
        amenities:
          type: array
          description: >-
            The list of amenity identifiers available at the property.
          items:
            type: string
        house_rules:
          type: string
          description: >-
            The house rules and guidelines for guests.
        check_in_time:
          type: string
          description: >-
            The earliest check-in time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        check_out_time:
          type: string
          description: >-
            The latest check-out time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        cancellation_policy:
          type: string
          description: >-
            The cancellation policy applied to the listing.
          enum:
          - flexible
          - moderate
          - strict
          - strict_14_with_grace_period
          - super_strict_30
          - super_strict_60
    ListingUpdate:
      type: object
      properties:
        name:
          type: string
          description: >-
            The display name of the listing.
          maxLength: 50
        description:
          type: string
          description: >-
            The full description of the property.
          maxLength: 5000
        property_type:
          type: string
          description: >-
            The type of property being listed.
          enum:
          - apartment
          - house
          - secondary_unit
          - unique_space
          - bed_and_breakfast
          - boutique_hotel
        room_type:
          type: string
          description: >-
            The type of room or space being offered.
          enum:
          - entire_home
          - private_room
          - shared_room
        bedrooms:
          type: integer
          description: >-
            The number of bedrooms in the property.
          minimum: 0
        bathrooms:
          type: number
          description: >-
            The number of bathrooms in the property.
          minimum: 0
        beds:
          type: integer
          description: >-
            The total number of beds in the property.
          minimum: 0
        max_guests:
          type: integer
          description: >-
            The maximum number of guests allowed.
          minimum: 1
        amenities:
          type: array
          description: >-
            The list of amenity identifiers available at the property.
          items:
            type: string
        house_rules:
          type: string
          description: >-
            The house rules and guidelines for guests.
        check_in_time:
          type: string
          description: >-
            The earliest check-in time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        check_out_time:
          type: string
          description: >-
            The latest check-out time in HH:MM format.
          pattern: '^[0-2][0-9]:[0-5][0-9]$'
        cancellation_policy:
          type: string
          description: >-
            The cancellation policy applied to the listing.
          enum:
          - flexible
          - moderate
          - strict
          - strict_14_with_grace_period
          - super_strict_30
          - super_strict_60
    Address:
      type: object
      required:
      - street
      - city
      - country
      properties:
        street:
          type: string
          description: >-
            The street address of the property.
        city:
          type: string
          description: >-
            The city where the property is located.
        state:
          type: string
          description: >-
            The state or province where the property is located.
        zip_code:
          type: string
          description: >-
            The postal or ZIP code.
        country:
          type: string
          description: >-
            The ISO 3166-1 alpha-2 country code.
          pattern: '^[A-Z]{2}$'
        latitude:
          type: number
          format: double
          description: >-
            The latitude coordinate of the property.
          minimum: -90
          maximum: 90
        longitude:
          type: number
          format: double
          description: >-
            The longitude coordinate of the property.
          minimum: -180
          maximum: 180
    Pricing:
      type: object
      properties:
        nightly_price:
          type: number
          format: double
          description: >-
            The base nightly price in the listing currency.
          minimum: 0
        currency:
          type: string
          description: >-
            The ISO 4217 currency code for pricing.
          pattern: '^[A-Z]{3}$'
        cleaning_fee:
          type: number
          format: double
          description: >-
            The one-time cleaning fee charged per reservation.
          minimum: 0
        weekly_discount:
          type: number
          description: >-
            The percentage discount for stays of 7 or more nights.
          minimum: 0
          maximum: 100
        monthly_discount:
          type: number
          description: >-
            The percentage discount for stays of 28 or more nights.
          minimum: 0
          maximum: 100
        extra_guest_fee:
          type: number
          format: double
          description: >-
            The additional fee per extra guest beyond the base occupancy.
          minimum: 0
    Photo:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the photo.
        url:
          type: string
          format: uri
          description: >-
            The URL where the photo is hosted.
        caption:
          type: string
          description: >-
            A caption describing the photo.
        sort_order:
          type: integer
          description: >-
            The display position of the photo in the listing gallery.
        width:
          type: integer
          description: >-
            The width of the photo in pixels.
        height:
          type: integer
          description: >-
            The height of the photo in pixels.
    CalendarDay:
      type: object
      properties:
        date:
          type: string
          format: date
          description: >-
            The date for this calendar entry.
        available:
          type: boolean
          description: >-
            Whether the listing is available for booking on this date.
        price:
          type: number
          format: double
          description: >-
            The nightly price for this date in the listing currency.
        minimum_nights:
          type: integer
          description: >-
            The minimum number of nights required for a stay starting
            on this date.
          minimum: 1
        maximum_nights:
          type: integer
          description: >-
            The maximum number of nights allowed for a stay starting
            on this date.
        reservation_id:
          type: string
          description: >-
            The reservation identifier if this date is booked.
    CalendarOperation:
      type: object
      required:
      - start_date
      - end_date
      properties:
        start_date:
          type: string
          format: date
          description: >-
            The start date of the range to update.
        end_date:
          type: string
          format: date
          description: >-
            The end date of the range to update.
        available:
          type: boolean
          description: >-
            Whether the dates should be available or blocked.
        price:
          type: number
          format: double
          description: >-
            The nightly price to set for this date range.
          minimum: 0
        minimum_nights:
          type: integer
          description: >-
            The minimum number of nights required for stays in this range.
          minimum: 1
        maximum_nights:
          type: integer
          description: >-
            The maximum number of nights allowed for stays in this range.
    Reservation:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the reservation.
        confirmation_code:
          type: string
          description: >-
            The human-readable confirmation code for the reservation.
        status:
          type: string
          description: >-
            The current status of the reservation.
          enum:
          - pending
          - accepted
          - denied
          - cancelled
          - checked_in
          - checked_out
        listing_id:
          type: string
          description: >-
            The identifier of the listing that was booked.
        guest:
          $ref: '#/components/schemas/Guest'
        check_in:
          type: string
          format: date
          description: >-
            The guest check-in date.
        check_out:
          type: string
          format: date
          description: >-
            The guest check-out date.
        nights:
          type: integer
          description: >-
            The total number of nights in the reservation.
          minimum: 1
        guests_count:
          type: integer
          description: >-
            The number of guests included in the reservation.
          minimum: 1
        total_price:
          type: number
          format: double
          description: >-
            The total price of the reservation in the listing currency.
        currency:
          type: string
          description: >-
            The ISO 4217 currency code for the reservation pricing.
          pattern: '^[A-Z]{3}$'
        host_payout:
          type: number
          format: double
          description: >-
            The amount to be paid out to the host after fees.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the reservation was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the reservation was last updated.
    Guest:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the guest.
        first_name:
          type: string
          description: >-
            The first name of the guest.
        last_name:
          type: string
          description: >-
            The last name of the guest.
        phone:
          type: string
          description: >-
            The phone number of the guest, available after booking is confirmed.
        profile_picture_url:
          type: string
          format: uri
          description: >-
            The URL of the guest profile picture.
        verified:
          type: boolean
          description: >-
            Whether the guest has completed identity verification.
    Message:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the message.
        reservation_id:
          type: string
          description: >-
            The identifier of the associated reservation.
        sender_type:
          type: string
          description: >-
            Whether the message was sent by the host or guest.
          enum:
          - host
          - guest
        message:
          type: string
          description: >-
            The text content of the message.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the message was sent.
    Review:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique identifier of the review.
        reservation_id:
          type: string
          description: >-
            The identifier of the associated reservation.
        reviewer_type:
          type: string
          description: >-
            Whether the review was written by a guest or host.
          enum:
          - guest
          - host
        rating:
          type: integer
          description: >-
            The overall star rating from 1 to 5.
          minimum: 1
          maximum: 5
        comments:
          type: string
          description: >-
            The text content of the review.
        category_ratings:
          type: object
          description: >-
            Individual category ratings provided by the reviewer.
          properties:
            cleanliness:
              type: integer
              minimum: 1
              maximum: 5
              description: >-
                Rating for cleanliness.
            communication:
              type: integer
              minimum: 1
              maximum: 5
              description: >-
                Rating for communication.
            check_in:
              type: integer
              minimum: 1
              maximum: 5
              description: >-
                Rating for check-in experience.
            accuracy:
              type: integer
              minimum: 1
              maximum: 5
              description: >-
                Rating for listing accuracy.
            location:
              type: integer
              minimum: 1
              maximum: 5
              description: >-
                Rating for location.
            value:
              type: integer
              minimum: 1
              maximum: 5
              description: >-
                Rating for value.
        host_response:
          type: string
          description: >-
            The host response to the review, if provided.
        created_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the review was submitted.
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: >-
            The total number of results available.
        limit:
          type: integer
          description: >-
            The number of results returned per page.
        offset:
          type: integer
          description: >-
            The current offset in the result set.
        has_more:
          type: boolean
          description: >-
            Whether more results are available beyond this page.