openapi.yaml

openapi: 3.1.0
info:
  title: Hospitable Public API
  version: "2.0"
  description: |
    The Hospitable Public API allows you to manage calendars, reservations, properties, and more in a programmatic way, using conventional HTTP requests.
    
    The API conforms to REST architectural standards and uses OAuth 2.0 for authentication.
    
    Key features:
    - Manage properties, reservations, and calendars
    - Automated guest messaging
    - Multi-platform synchronization (Airbnb, Vrbo, Booking.com)
    - Webhook support for real-time updates
    - Dynamic pricing and availability management
  contact:
    name: Hospitable Platform Team
    email: team-platform@hospitable.com
  externalDocs:
    description: Official API Documentation
    url: https://developer.hospitable.com/docs/public-api-docs/

servers:
  - url: https://public.api.hospitable.com/v2
    description: Production server

security:
  - Bearer-Authorization: []

components:
  securitySchemes:
    Bearer-Authorization:
      type: http
      scheme: bearer
      description: Enter the token with the `Bearer ` prefix, e.g. `Bearer abcde12345`

  schemas:
    # Core Property Schema
    Property:
      type: object
      required:
        - id
        - name
        - public_name
        - picture
        - address
        - timezone
        - listed
        - amenities
        - description
        - summary
        - check-in
        - check-out
        - currency
        - capacity
        - room_details
        - house_rules
        - listings
        - tags
        - property_type
        - room_type
        - calendar_restricted
      properties:
        id:
          type: string
          format: uuid
          examples: ["550e8400-e29b-41d4-a716-446655440000"]
        name:
          type: string
          examples: ["Relaxing Villa near the sea"]
        public_name:
          type: string
          examples: ["Relaxing Villa near the sea"]
        picture:
          type: string
          format: uri
          examples: ["https://cdn2.thecatapi.com/images/d9m.jpg"]
        address:
          type: object
          required: [number, street, city, state, country, postcode, coordinates, display]
          properties:
            number:
              type: string
              description: Apartment or unit number
              examples: ["32"]
            street:
              type: string
              examples: ["Senefelderplatz"]
            city:
              type: string
              examples: ["Berlin"]
            state:
              type: string
            country:
              type: string
              examples: ["DE"]
            postcode:
              type: string
              examples: ["10405"]
            coordinates:
              type: object
              required: [latitude, longitude]
              properties:
                latitude:
                  type: number
                  format: float
                  examples: [50.8514786]
                longitude:
                  type: number
                  format: float
                  examples: [4.364562]
            display:
              type: string
              examples: ["37a Senefelderplatz, 10405 Berlin, DE"]
        timezone:
          type: string
          examples: ["+0200"]
        listed:
          type: boolean
          examples: [true]
        amenities:
          type: array
          items:
            type: string
            examples: ["shower"]
        description:
          type: string
          examples: ["Example Description"]
        summary:
          type: string
          examples: ["Example Summary"]
        check-in:
          type: string
          description: The default checkin time for the property
          examples: ["12:30"]
        check-out:
          type: string
          description: The default checkout time for the property
          examples: ["12:30"]
        currency:
          type: string
          examples: ["EUR"]
        capacity:
          type: object
          properties:
            max:
              type: integer
              nullable: true
              examples: [2]
            bedrooms:
              type: integer
              nullable: true
              examples: [1]
            beds:
              type: number
              nullable: true
              examples: [1]
            bathrooms:
              type: number
              nullable: true
              examples: [1.5]
        room_details:
          type: array
          items:
            type: object
            required: [type, quantity]
            properties:
              type:
                type: string
                examples: ["king_size"]
              quantity:
                type: integer
                examples: [1]
        house_rules:
          type: object
          required: [pets_allowed, smoking_allowed, events_allowed]
          properties:
            pets_allowed:
              type: boolean
              examples: [true]
            smoking_allowed:
              type: boolean
              examples: [false]
            events_allowed:
              nullable: true
        listings:
          type: array
          items:
            type: object
            required: [platform, platform_id]
            properties:
              platform:
                type: string
                examples: ["airbnb"]
              platform_id:
                type: string
                description: This is the listing id used on the platform
                examples: ["24488"]
              platform_name:
                type: string
                description: "`pat:read` scope only"
              platform_email:
                type: string
                description: "`pat:read` scope only"
        ical_imports:
          type: array
          description: iCal import feeds for this property. Only included when 'listings' is included.
          items:
            type: object
            required: [uuid, url, name, host, last_sync_at, disconnected_at]
            properties:
              uuid:
                type: string
                format: uuid
                description: The unique identifier for this iCal import
                examples: ["550e8400-e29b-41d4-a716-446655440000"]
              url:
                type: string
                format: uri
                description: The URL of the iCal feed
                examples: ["https://example.com/calendar.ics"]
              name:
                type: string
                nullable: true
                description: A friendly name for this iCal import
                examples: ["Vacation Rental Calendar"]
              host:
                type: object
                required: [first_name, last_name]
                properties:
                  first_name:
                    type: string
                    nullable: true
                    examples: ["John"]
                  last_name:
                    type: string
                    nullable: true
                    examples: ["Doe"]
              last_sync_at:
                type: string
                format: date-time
                nullable: true
                examples: ["2019-01-01T12:00:00Z"]
              disconnected_at:
                type: string
                format: date-time
                nullable: true
                examples: ["2019-01-01T12:00:00Z"]
        tags:
          type: array
          items:
            type: string
            examples: ["Tag"]
        property_type:
          type: string
        room_type:
          type: string
        calendar_restricted:
          type: boolean
          description: If a property is `calendar_restricted` its calendar will not be able to be updated using the Update Property Calendar endpoint
        parent_child:
          type: object
          nullable: true
          description: If the property is in a Parent/Child setup then this will contain all the information about that relationship
          properties:
            type:
              type: string
              enum: [parent, child]
              description: If this property is the parent or child in the relationship
            parent:
              type: string
              nullable: true
              description: If this property is a child, this is the parent property id
              examples: ["550e8400-e29b-41d4-a716-446655440000"]
            children:
              type: array
              description: If this property is a parent, this is any child property ids
              items:
                type: string
                format: uuid
                examples: ["550e8400-e29b-41d4-a716-446655440000"]
            siblings:
              type: array
              description: If this property is a child, this is any sibling property ids
              items:
                type: string
                format: uuid
                examples: ["550e8400-e29b-41d4-a716-446655440000"]

    # Reservation Schema
    Reservation:
      type: object
      required:
        - id
        - conversation_id
        - platform
        - platform_id
        - booking_date
        - arrival_date
        - departure_date
        - nights
        - check_in
        - check_out
        - last_message_at
        - status
        - reservation_status
        - status_history
        - guests
      properties:
        id:
          type: string
          format: uuid
          examples: ["6f58fd0a-a9cb-3746-9219-384a156ff7bb"]
        conversation_id:
          type: string
          format: uuid
          examples: ["6f58fd0a-a9cb-3746-9219-384a156ff7bb"]
        platform:
          type: string
          enum: [airbnb, homeaway, booking, direct, manual]
          readOnly: true
          examples: ["homeaway"]
        platform_id:
          type: string
          description: The reservation code
          examples: ["ABC123"]
        booking_date:
          type: string
          format: date-time
          examples: ["2019-01-01T12:00:00Z"]
        arrival_date:
          type: string
          format: date-time
          description: This provides only the date, not the exact check-in time. Refer to check_in.
          examples: ["2019-01-03T00:00:00-05:00"]
        departure_date:
          type: string
          format: date-time
          description: This provides only the date, not the exact check-out time. Refer to check_out.
          examples: ["2019-01-05T00:00:00-05:00"]
        nights:
          type: integer
        check_in:
          type: string
          format: date-time
          examples: ["2019-01-03T13:00:00-05:00"]
        check_out:
          type: string
          format: date-time
          examples: ["2019-01-05T11:00:00-05:00"]
        last_message_at:
          type: string
          format: date-time
          examples: ["2019-01-05T11:00:00-00:00"]
        status:
          type: string
          examples: ["booking"]
          deprecated: true
        reservation_status:
          type: object
          required: [current, history]
          properties:
            current:
              $ref: '#/components/schemas/ReservationStatus'
            history:
              type: array
              items:
                allOf:
                  - $ref: '#/components/schemas/ReservationStatus'
                  - type: object
                    required: [changed_at]
                    properties:
                      changed_at:
                        type: string
                        format: date-time
                        examples: ["2019-01-03T12:00:00-05:00"]
        status_history:
          type: array
          deprecated: true
          items:
            type: object
            required: [category, sub_category, changed_at]
            properties:
              category:
                type: string
                examples: ["accepted"]
              sub_category:
                type: string
                nullable: true
                examples: ["accepted"]
              changed_at:
                type: string
                format: date-time
                examples: ["2019-01-03T12:00:00-05:00"]
        guests:
          type: object
          required: [total, adult_count, child_count, infant_count, pet_count]
          properties:
            total:
              type: integer
              examples: [1]
            adult_count:
              type: integer
              examples: [1]
            child_count:
              type: integer
              examples: [0]
            infant_count:
              type: integer
              examples: [0]
            pet_count:
              type: integer
              examples: [0]
        issue_alert:
          type: string
          nullable: true
          description: Any guest issues that have been detected on the reservation
          examples: ["Broken AC"]
        stay_type:
          type: string
          enum: [guest_stay, owner_stay]

    ReservationStatus:
      type: object
      required: [category, sub_category]
      properties:
        category:
          type: string
          enum: [request, accepted, cancelled, not accepted, unknown, checkpoint]
          description: The overall status of the reservation
        sub_category:
          type: string
          enum: [pending verification, awaiting approval, request to book, request for payment, declined, withdrawn, expired, checkpoint, voided]
          description: The status of the reservation within a category

    # Message Schema
    Message:
      type: object
      properties:
        platform:
          type: string
          examples: ["airbnb"]
        platform_id:
          type: integer
          examples: [1130024]
        conversation_id:
          type: string
          examples: ["becd1474-ccd1-40bf-9ce8-04456bfa338d"]
        reservation_id:
          type: string
          nullable: true
          examples: ["becd1474-ccd1-40bf-9ce8-04456bfa338d"]
        content_type:
          type: string
          examples: ["text/plain"]
        body:
          type: string
          examples: ["Hello, there."]
        attachments:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum: [image]
              url:
                type: string
                description: The image location URL
        sender_type:
          type: string
          examples: ["host", "guest"]
        sender_role:
          type: string
          examples: ["host", "co-host", "teammate", "null"]
        sender:
          type: object
          properties:
            first_name:
              type: string
              examples: ["Jane"]
            full_name:
              type: string
              examples: ["Jane Doe"]
            locale:
              type: string
              examples: ["en"]
            picture_url:
              type: string
              format: uri
            thumbnail_url:
              type: string
              format: uri
            location:
              nullable: true
        user:
          type: object
          properties:
            id:
              type: string
              format: uuid
            email:
              type: string
              format: email
            name:
              type: string
        created_at:
          type: string
          format: date-time
          examples: ["2019-07-29T19:01:14Z"]
        source:
          type: string
          enum: [public_api, platform, AI, automated, hospitable]
          description: |
            The source of the message:
            - **public_api**: sent using the API, either using an access token or by an integration partner
            - **platform**: Sent through the booking channel's native messaging platform
            - **hospitable**: sent from within Hospitable
            - **automated**: a scheduled or event based automated message
            - **AI**: Sent using Hospitable auto-reply
        integration:
          type: string
          nullable: true
          description: |
            **Personal Access Token only!**
            If the message was sent using an integration, then the name of the integration partner will be returned.
        sent_reference_id:
          type: string
          nullable: true
          description: The message identifier provided if the message was sent using one of the Send Message endpoints

    # Financial Schemas
    FinancialV2:
      type: object
      properties:
        amount:
          type: integer
          examples: [12345]
        formatted:
          type: string
          examples: ["$123.45"]

    NegativeFinancial:
      type: object
      properties:
        amount:
          type: integer
          examples: [-12345]
        formatted:
          type: string
          examples: ["$-123.45"]

    # Calendar Schema
    CalendarDay:
      type: object
      properties:
        date:
          type: string
          format: date
          examples: ["2023-10-01"]
        day:
          type: string
          examples: ["SUNDAY"]
        min_stay:
          type: integer
        status:
          type: object
          properties:
            reason:
              type: string
              enum: [RESERVED, AVAILABLE, BLOCKED]
              description: "`BLOCKED` is used for all other reasons a date is unavailable"
            source_type:
              type: string
              enum: [USER, VENDOR, PLATFORM, AVAILABILITY_WINDOW, TURNOVER_DAY, ADVANCED_NOTICE, UPSELL, RESERVATION]
              nullable: true
              description: The source of the availability
            source:
              type: string
              nullable: true
              description: The source of the availability
              examples: ["Airbnb"]
            available:
              type: boolean
              examples: [false]
        price:
          type: object
          properties:
            amount:
              type: integer
              examples: [15000]
            currency:
              type: string
              examples: ["EUR"]
            formatted:
              type: string
              examples: ["€150.00"]
        closed_for_checkin:
          type: boolean
        closed_for_checkout:
          type: boolean

    # Review Schema
    Review:
      type: object
      required: [id, platform, public, private]
      properties:
        id:
          type: string
          format: uuid
          examples: ["550e8400-e29b-41d4-a716-446655440000"]
        platform:
          type: string
          enum: [airbnb, direct]
          examples: ["airbnb"]
        public:
          type: object
          required: [rating, review, response]
          properties:
            rating:
              type: integer
              minimum: 1
              maximum: 5
            review:
              type: string
              examples: ["Great place we will be back!"]
            response:
              type: string
              examples: ["So happy you enjoyed it so much!"]
        private:
          type: object
          required: [feedback]
          properties:
            feedback:
              type: string
              examples: ["downstairs was a bit cold."]
            detailed_ratings:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum: [cleanliness, communication, location, checkin, accuracy, value]
                  rating:
                    type: integer
                    minimum: 1
                    maximum: 5
                  comment:
                    type: string
                    examples: ["The cabin was cozy and comfy."]
        responded_at:
          type: string
          format: date-time
        reviewed_at:
          type: string
          format: date-time
          examples: ["2024-03-19T10:00:00Z"]
        can_respond:
          type: boolean
        guest:
          type: object
          required: [first_name, last_name]
          properties:
            first_name:
              type: string
            last_name:
              type: string
            language:
              type: string
              description: The guest's preferred language

    # Pagination Schema
    PaginationMeta:
      type: object
      properties:
        current_page:
          type: integer
          examples: [1]
        from:
          type: integer
          examples: [1]
        last_page:
          type: integer
          examples: [50]
        per_page:
          type: integer
          examples: [10]
        to:
          type: integer
          examples: [10]
        total:
          type: integer
          examples: [100]
        links:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
                nullable: true
              label:
                type: string
                examples: ["« Previous"]
              active:
                type: boolean
                examples: [false]

    # Error Schema
    Error:
      type: object
      properties:
        status_code:
          type: integer
          examples: [400]
        reason_phrase:
          type: string
          examples: ["Invalid pagination parameter supplied."]
        message:
          type: string
          examples: ["The given data was invalid."]

paths:
  # Properties endpoints
  /properties:
    get:
      summary: Get Properties
      description: |
        Retrieve a list of properties associated with your account.
        
        **Available includes:**
        - user
        - listings (required: `listing:read` scope)
        - details
        - bookings
      tags: [Properties]
      parameters:
        - name: include
          in: query
          description: What relationships should be included in the response
          schema:
            type: string
            examples: ["listings"]
        - name: page
          in: query
          description: The page of results to return
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: The number of results to include per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Property'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /properties/search:
    get:
      summary: Search Properties
      description: |
        Search for properties with availability and pricing for specific dates.
        
        This endpoint allows you to search up to **3 years** in the future and for a max period of **90 days**.
        
        **Available includes:**
        - listings (required: `listing:read` scope)
        - details
        
        Requires the customer to have a Self-hosted site created in Direct, with the properties scoped.
      tags: [Properties]
      parameters:
        - name: include
          in: query
          description: What relationships should be included in the response
          schema:
            type: string
            examples: ["listings"]
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            format: date
            examples: ["2024-08-16"]
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            format: date
            examples: ["2024-10-21"]
        - name: adults
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
        - name: children
          in: query
          schema:
            type: integer
            minimum: 0
        - name: infants
          in: query
          schema:
            type: integer
            minimum: 0
        - name: pets
          in: query
          schema:
            type: integer
            minimum: 0
        - name: location
          in: query
          style: deepObject
          schema:
            type: object
            required: [latitude, longitude]
            properties:
              latitude:
                type: number
                format: float
              longitude:
                type: number
                format: float
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        property:
                          $ref: '#/components/schemas/Property'
                        pricing:
                          type: object
                          properties:
                            daily:
                              type: array
                              items:
                                type: object
                                properties:
                                  date:
                                    type: string
                                    format: date
                                  price:
                                    $ref: '#/components/schemas/FinancialV2'
                            total_without_taxes:
                              $ref: '#/components/schemas/FinancialV2'
                            total:
                              $ref: '#/components/schemas/FinancialV2'
                        availability:
                          type: object
                          properties:
                            available:
                              type: boolean
                            details:
                              type: array
                              items:
                                type: object
                                properties:
                                  notAvailableReason:
                                    type: string
                                  date:
                                    type: string
                                    format: date-time
                        distance_in_km:
                          type: integer

  /properties/{uuid}:
    get:
      summary: Get Property by UUID
      description: |
        Retrieve a specific property by its ID.
        
        **Available includes:**
        - user
        - listings (required: `listing:read` scope)
        - details
        - bookings
      tags: [Properties]
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the property to retrieve
          schema:
            type: string
            format: uuid
        - name: include
          in: query
          description: What relationships should be included in the response
          schema:
            type: string
            examples: ["listings"]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Property'

  /properties/{uuid}/calendar:
    get:
      summary: Get Property Calendar
      description: |
        Retrieve calendar data including availability and pricing.
        
        **Required scopes:**
        - `property:read`
        - `calendar:read`
      tags: [Properties]
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the property
          schema:
            type: string
            format: uuid
        - name: start_date
          in: query
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      start_date:
                        type: string
                        format: date
                      end_date:
                        type: string
                        format: date
                      days:
                        type: array
                        items:
                          $ref: '#/components/schemas/CalendarDay'

    put:
      summary: Update Property Calendar
      description: |
        Update pricing and availability for specific dates.
        
        Allows updating a property's calendar data for up to 1,095 days (3 years) into the future.
        
        **Required scopes:**
        - `property:read`
        - `calendar:write`
        
        **Rate limit**: 1000 requests per minute for the calendar endpoint.
      tags: [Properties]
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the property to update
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dates:
                  type: array
                  items:
                    type: object
                    maxProperties: 60
                    additionalProperties: false
                    properties:
                      date:
                        type: string
                        format: date
                        description: YYYY-MM-DD format
                      price:
                        type: object
                        properties:
                          amount:
                            type: integer
                            description: Amount in base units (e.g. cents for USD or EUR)
                            examples: [1000]
                      available:
                        type: boolean
                        description: Is this date available?
                      min_stay:
                        type: integer
                        description: Minimum nights stay
                        examples: [3]
                      closed_for_checkout:
                        type: boolean
                        description: Is the date available for checkout?
                      closed_for_checkin:
                        type: boolean
                        description: Is the date available for checkin?
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    examples: ["accepted"]

  # Reservations endpoints
  /reservations:
    get:
      summary: Get Reservations
      description: |
        Retrieve a list of reservations.
        
        **Available includes:**
        - guest
        - user
        - financials (required: `financials:read` scope)
        - listings (required: `listing:read` scope)
        - properties (required: `property:read` scope)
        - review (required: `reviews:read` scope)
        
        We will default to reservations with check-in dates in the next 2 weeks if at least one of these query parameters are not provided:
        - `start_date`
        - `end_date`
        - `date_query`
      tags: [Reservations]
      parameters:
        - name: properties[]
          in: query
          required: true
          description: Array of property UUIDs to query for
          schema:
            type: array
            items:
              type: string
              format: uuid
        - name: start_date
          in: query
          description: Find reservations with check-in/check-out dates after this day
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          description: Find reservations with check-in/check-out dates before this day
          schema:
            type: string
            format: date
        - name: include
          in: query
          description: Comma-separated values, any of
          schema:
            type: string
            examples: ["financials,guest,properties,listings"]
        - name: date_query
          in: query
          description: Configure whether to use your date values to search by 'checkin' or 'checkout'
          schema:
            type: string
            default: "checkin"
        - name: platform_id
          in: query
          description: Find reservations with a reservation code that exactly matches the one given
          schema:
            type: string
        - name: conversation_id
          in: query
          description: Find reservations with a conversation id that exactly matches the one given
          schema:
            type: string
        - name: last_message_at
          in: query
          description: Find reservations where the last message is after the specified datetime
          schema:
            type: string
            format: date-time
        - name: page
          in: query
          description: The page number you would like to retrieve
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: The number of results to include per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reservation'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'

  /reservations/{uuid}:
    get:
      summary: Get Reservation by UUID
      description: |
        Retrieve a specific reservation by its ID.
        
        **Available includes:**
        - guest
        - user
        - financials (required: `financials:read` scope)
        - financialsV2 (required: `financials:read` scope)
        - listings (required: `listing:read` scope)
        - properties (required: `property:read` scope)
      tags: [Reservations]
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the reservation to retrieve
          schema:
            type: string
            format: uuid
        - name: include
          in: query
          description: Comma-separated values, any of
          schema:
            type: string
            examples: ["financials,guest,properties,listings"]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Reservation'

  # Messages endpoints
  /reservations/{uuid}/messages:
    get:
      summary: Get Reservation Messages
      description: |
        Retrieve messages for a specific reservation.
        
        **Required scopes:**
        - message:read
      tags: [Messaging]
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the reservation
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'

    post:
      summary: Send Message for Reservation
      description: |
        Send a message to the guest for a specific reservation.
        
        **Required scopes:**
        - message:write
        
        Please write to team-platform@hospitable.com in order to get this scope added to your token.
        
        **Rate Limits:**
        - Only 2 messages per minute can be sent to a single reservation
        - Only 50 messages can be sent every 5 minutes
      tags: [Messaging]
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the reservation
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: string
                  description: |
                    Text body of the message to send. Note:
                    - HTML is not supported.
                    - `/n` is parsed for line breaks.
                images:
                  type: array
                  description: |
                    The URL location of any images to attach to the message.
                    - Maximum of 3 images.
                    - The maximum filesize is 5MB.
                  maxItems: 3
                  items:
                    type: string
                    format: uri
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      sent_reference_id:
                        type: string
                        description: A unique identifier that can be used to match a send message request with a Message resource
                        examples: ["2d637b98-2e20-470e-a582-83c4304d48a8"]

  # Reviews endpoints
  /properties/{uuid}/reviews:
    get:
      summary: Get Property Reviews
      description: |
        Returns a paginated list of reviews that guests have left for a specific property. 
        Currently, we source review data from Airbnb and our own direct bookings.
        
        **Required scopes:**
        - reviews:read
        
        **Available includes:**
        - guest
        - reservations
      tags: [Reviews]
      parameters:
        - name: uuid
          in: path
          required: true
          description: UUID of the property
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          description: Page number of results
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Number of results per page
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
        - name: include
          in: query
          description: Comma-separated values, any of
          schema:
            type: string
            examples: ["guest"]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Review'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'

  /reviews/{uuid}/respond:
    post:
      summary: Respond to a review
      description: |
        Response to a review received for a reservation.
        
        **Required scopes:**
        - reviews:write
      tags: [Reviews]
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the review
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [response]
              properties:
                response:
                  type: string
                  description: The response text to the review
      responses:
        '200':
          description: Review response submitted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Review'
        '403':
          description: |
            If the review cannot be responded to because:
            - It has already been responded to
            - The review has not been responded to within the response window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  # User endpoint
  /user:
    get:
      summary: Get User & Billing
      description: Retrieve information about the authenticated user and their billing details
      tags: [User]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        examples: ["5c05eb47-b6ec-54fe-b4b9-6e95f50b86d0"]
                      email:
                        type: string
                        format: email
                        examples: ["john.doe@hotmail.com"]
                      name:
                        type: string
                        examples: ["John Doe"]
                      business:
                        type: boolean
                        examples: [true]
                      company:
                        type: string
                        examples: ["Johny Doe & Co"]
                      vat:
                        nullable: true
                      tax_id:
                        nullable: true
                      street_line1:
                        type: string
                        examples: ["878 PEACHTREE ST"]
                      street_line2:
                        nullable: true
                      postal_code:
                        type: integer
                        examples: [30301]
                      city:
                        type: string
                        examples: ["Atlanta"]
                      region:
                        nullable: true
                      country:
                        type: string
                        examples: ["United States"]

tags:
  - name: Properties
    description: Manage vacation rental properties
  - name: Reservations
    description: Manage bookings and reservations
  - name: Messaging
    description: Manage guest communication
  - name: Reviews
    description: Manage property reviews and ratings
  - name: User
    description: User account and billing information

webhooks:
  reservationCreated:
    post:
      description: Webhook payload when a new reservation is created
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: A unique ordered ID assigned to the payload
                action:
                  type: string
                  enum: [reservation.created]
                data:
                  $ref: '#/components/schemas/Reservation'
                created:
                  type: string
                  format: date-time
                  description: When the payload was initially created
                version:
                  type: string
                  description: Version of the webhook
                  examples: ["1.0"]
      responses:
        '200':
          description: Webhook received successfully

  reservationUpdated:
    post:
      description: Webhook payload when a reservation is updated
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: A unique ordered ID assigned to the payload
                action:
                  type: string
                  enum: [reservation.updated]
                data:
                  $ref: '#/components/schemas/Reservation'
                created:
                  type: string
                  format: date-time
                version:
                  type: string
                  examples: ["1.0"]
      responses:
        '200':
          description: Webhook received successfully

  propertyUpdated:
    post:
      description: Webhook payload when a property is updated
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                action:
                  type: string
                  enum: [property.updated, property.merged]
                data:
                  $ref: '#/components/schemas/Property'
                created:
                  type: string
                  format: date-time
                version:
                  type: string
                  examples: ["1.0"]
      responses:
        '200':
          description: Webhook received successfully

  messageCreated:
    post:
      description: Webhook payload when a new message is created
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                action:
                  type: string
                  enum: [message.created]
                data:
                  $ref: '#/components/schemas/Message'
                created:
                  type: string
                  format: date-time
                version:
                  type: string
                  examples: ["1.0"]
      responses:
        '200':
          description: Webhook received successfully

  reviewCreated:
    post:
      description: Webhook payload when a new review is created
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                action:
                  type: string
                  enum: [review.created]
                data:
                  $ref: '#/components/schemas/Review'
                created:
                  type: string
                  format: date-time
                version:
                  type: string
                  examples: ["1.0"]
      responses:
        '200':
          description: Webhook received successfully