openapi: 3.0.1
info:
  title: Lodgify Public API
  description: >-
    The Lodgify Public API is a REST interface for the Lodgify vacation rental
    platform. It exposes properties and room types, availability calendars,
    daily rates, rate settings, priced quotes, the full booking and reservation
    lifecycle, guest messaging threads, and webhook subscriptions. The API spans
    two versions (v1 and v2) under the host https://api.lodgify.com and is
    authenticated with an X-ApiKey request header.
  termsOfService: https://www.lodgify.com/legal-stuff/
  contact:
    name: Lodgify Support
    url: https://docs.lodgify.com
  version: '2.0'
servers:
  - url: https://api.lodgify.com
    description: Lodgify Public API (v1 and v2 paths)
security:
  - ApiKeyAuth: []
tags:
  - name: Properties
    description: Vacation rental properties and their room types.
  - name: Availability
    description: Availability calendars for properties and room types.
  - name: Rates & Quotes
    description: Daily rates, rate settings, and priced stay quotes.
  - name: Bookings
    description: Booking and reservation lifecycle management.
  - name: Messaging
    description: Guest conversation threads and messages.
  - name: Webhooks
    description: Event subscriptions for real-time notifications.
paths:
  /v2/properties:
    get:
      operationId: listProperties
      tags:
        - Properties
      summary: List properties
      description: Returns a paged list of all properties on the account.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - name: includeCount
          in: query
          schema:
            type: boolean
          description: Whether to include the total count in the response.
      responses:
        '200':
          description: A paged list of properties.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/properties/{id}:
    get:
      operationId: getProperty
      tags:
        - Properties
      summary: Get a property
      description: Returns the details of a single property by its identifier.
      parameters:
        - $ref: '#/components/parameters/PropertyId'
      responses:
        '200':
          description: The requested property.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Property'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/properties/{id}/rooms:
    get:
      operationId: listPropertyRooms
      tags:
        - Properties
      summary: List property room types
      description: Returns the room types configured for a property.
      parameters:
        - $ref: '#/components/parameters/PropertyId'
      responses:
        '200':
          description: A list of room types for the property.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Room'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/availability/{propertyId}:
    get:
      operationId: getPropertyAvailability
      tags:
        - Availability
      summary: Get property availability
      description: >-
        Returns the availability calendar for a property over a date range,
        listing available and booked periods per room type.
      parameters:
        - name: propertyId
          in: path
          required: true
          schema:
            type: integer
            format: int32
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
      responses:
        '200':
          description: Availability periods for the property.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailabilityPeriod'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/rates/calendar:
    get:
      operationId: getDailyRates
      tags:
        - Rates & Quotes
      summary: Get daily rates
      description: >-
        Returns the daily rates calendar for the requested room types, by
        roomTypeId or houseId, over a date range.
      parameters:
        - name: HouseId
          in: query
          schema:
            type: integer
            format: int32
        - name: RoomTypeId
          in: query
          schema:
            type: integer
            format: int32
        - name: StartDate
          in: query
          schema:
            type: string
            format: date
        - name: EndDate
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Daily rate entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DailyRate'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/rates/settings:
    get:
      operationId: getRateSettings
      tags:
        - Rates & Quotes
      summary: Get rate settings
      description: Returns the rate settings for the given houseId.
      parameters:
        - name: HouseId
          in: query
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Rate settings for the property.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateSettings'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/rates/savewithoutavailability:
    post:
      operationId: updateRates
      tags:
        - Rates & Quotes
      summary: Update rates
      description: Saves or updates rates for room types without changing availability.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RateUpdate'
      responses:
        '200':
          description: Rates updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/quote/{propertyId}:
    get:
      operationId: getQuote
      tags:
        - Rates & Quotes
      summary: Get a quote
      description: >-
        Returns a priced quote for a stay at a property, including the room
        rate, fees, taxes, and any applicable discounts.
      parameters:
        - name: propertyId
          in: path
          required: true
          schema:
            type: integer
            format: int32
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - name: 'roomTypes[0].Id'
          in: query
          schema:
            type: integer
            format: int32
        - name: 'guest_breakdown[adults]'
          in: query
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A priced quote for the requested stay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings:
    get:
      operationId: listBookings
      tags:
        - Bookings
      summary: List bookings
      description: Returns a paged list of bookings filtered by status, date, and channel.
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/Size'
        - name: stayFilter
          in: query
          schema:
            type: string
            enum: [Upcoming, Current, Historic, All]
      responses:
        '200':
          description: A paged list of bookings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BookingList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBooking
      tags:
        - Bookings
      summary: Create a booking
      description: Creates a new booking, optionally upgrading an existing enquiry.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCreate'
      responses:
        '201':
          description: The created booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}:
    get:
      operationId: getBooking
      tags:
        - Bookings
      summary: Get a booking
      description: Returns the details of a single booking by its identifier.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: The requested booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateBooking
      tags:
        - Bookings
      summary: Update a booking
      description: Updates an existing booking.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BookingCreate'
      responses:
        '200':
          description: The updated booking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Booking'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteBooking
      tags:
        - Bookings
      summary: Delete a booking
      description: Deletes a booking.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      responses:
        '204':
          description: Booking deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/quote/paymentLink:
    get:
      operationId: getBookingPaymentLink
      tags:
        - Bookings
      summary: Get a booking payment link
      description: Returns the current payment link for a booking.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: The payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBookingPaymentLink
      tags:
        - Bookings
      summary: Create a booking payment link
      description: Creates a payment link for a booking.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentLinkCreate'
      responses:
        '201':
          description: The created payment link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/keyCodes:
    put:
      operationId: updateKeyCodes
      tags:
        - Bookings
      summary: Update key codes
      description: Sets or updates the key codes associated with a booking.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KeyCodes'
      responses:
        '200':
          description: Key codes updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/checkin:
    put:
      operationId: checkinBooking
      tags:
        - Bookings
      summary: Check in a booking
      description: Marks a booking as checked in.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: Booking checked in.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/reservations/bookings/{id}/checkout:
    put:
      operationId: checkoutBooking
      tags:
        - Bookings
      summary: Check out a booking
      description: Marks a booking as checked out.
      parameters:
        - $ref: '#/components/parameters/BookingId'
      responses:
        '200':
          description: Booking checked out.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/messaging/{threadGuid}:
    get:
      operationId: getThread
      tags:
        - Messaging
      summary: Get a messaging thread
      description: Returns a guest conversation thread and its messages by thread GUID.
      parameters:
        - name: threadGuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: The conversation thread.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Thread'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /webhooks/v1/list:
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhook subscriptions
      description: Returns all active webhook subscriptions for the account.
      responses:
        '200':
          description: A list of webhook subscriptions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/v1/subscribe:
    post:
      operationId: subscribeWebhook
      tags:
        - Webhooks
      summary: Subscribe to a webhook event
      description: >-
        Subscribes a unique target URL to a given event. When the event occurs
        the target URL is called with event-related information and should
        return a 200 OK response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscribe'
      responses:
        '200':
          description: Subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/v1/unsubscribe:
    delete:
      operationId: unsubscribeWebhook
      tags:
        - Webhooks
      summary: Unsubscribe from a webhook event
      description: Removes a webhook subscription by its identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookUnsubscribe'
      responses:
        '200':
          description: Subscription removed.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/v1/{id}:
    delete:
      operationId: deleteWebhook
      tags:
        - Webhooks
      summary: Delete a webhook subscription
      description: Deletes a specific webhook subscription by its identifier.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Subscription deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-ApiKey
      description: Account API key passed in the X-ApiKey request header.
  parameters:
    Page:
      name: page
      in: query
      schema:
        type: integer
        format: int32
        default: 1
      description: 1-based page number.
    Size:
      name: size
      in: query
      schema:
        type: integer
        format: int32
        default: 50
      description: Number of items per page.
    PropertyId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int32
      description: Property identifier.
    BookingId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int32
      description: Booking identifier.
    From:
      name: from
      in: query
      schema:
        type: string
        format: date
      description: Start date (YYYY-MM-DD).
    To:
      name: to
      in: query
      schema:
        type: string
        format: date
      description: End date (YYYY-MM-DD).
  responses:
    Unauthorized:
      description: Missing or invalid X-ApiKey.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    PropertyList:
      type: object
      properties:
        count:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Property'
    Property:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        description:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        address:
          type: string
        city:
          type: string
        country_code:
          type: string
        currency_code:
          type: string
        rooms:
          type: array
          items:
            $ref: '#/components/schemas/Room'
    Room:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type: string
        max_people:
          type: integer
          format: int32
        bedrooms:
          type: integer
          format: int32
        bathrooms:
          type: number
          format: float
    AvailabilityPeriod:
      type: object
      properties:
        room_type_id:
          type: integer
          format: int32
        start:
          type: string
          format: date
        end:
          type: string
          format: date
        available:
          type: integer
          format: int32
        closed_period:
          type: boolean
        bookings:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int32
              status:
                type: string
    DailyRate:
      type: object
      properties:
        room_type_id:
          type: integer
          format: int32
        date:
          type: string
          format: date
        price_per_day:
          type: number
          format: double
        min_stay:
          type: integer
          format: int32
        max_stay:
          type: integer
          format: int32
        currency_code:
          type: string
    RateSettings:
      type: object
      properties:
        house_id:
          type: integer
          format: int32
        currency_code:
          type: string
        check_in_time:
          type: string
        check_out_time:
          type: string
    RateUpdate:
      type: object
      properties:
        property_id:
          type: integer
          format: int32
        rates:
          type: array
          items:
            type: object
            properties:
              room_type_id:
                type: integer
                format: int32
              start_date:
                type: string
                format: date
              end_date:
                type: string
                format: date
              price_per_day:
                type: number
                format: double
              min_stay:
                type: integer
                format: int32
    Quote:
      type: object
      properties:
        total_including_vat:
          type: number
          format: double
        currency_code:
          type: string
        room_types:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int32
              subtotal:
                type: number
                format: double
        amenities_subtotal:
          type: number
          format: double
        fees_subtotal:
          type: number
          format: double
        taxes_subtotal:
          type: number
          format: double
    BookingList:
      type: object
      properties:
        count:
          type: integer
          format: int32
        items:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
    Booking:
      type: object
      properties:
        id:
          type: integer
          format: int32
        property_id:
          type: integer
          format: int32
        status:
          type: string
          enum: [Open, Booked, Tentative, Declined]
        arrival:
          type: string
          format: date
        departure:
          type: string
          format: date
        guest:
          $ref: '#/components/schemas/Guest'
        total_amount:
          type: number
          format: double
        currency_code:
          type: string
        source:
          type: string
    BookingCreate:
      type: object
      required:
        - property_id
        - arrival
        - departure
      properties:
        property_id:
          type: integer
          format: int32
        room_types:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int32
              people:
                type: integer
                format: int32
        arrival:
          type: string
          format: date
        departure:
          type: string
          format: date
        guest:
          $ref: '#/components/schemas/Guest'
        status:
          type: string
          enum: [Open, Booked, Tentative]
    Guest:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
        country_code:
          type: string
    PaymentLink:
      type: object
      properties:
        url:
          type: string
          format: uri
        amount:
          type: number
          format: double
        currency:
          type: string
    PaymentLinkCreate:
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
        description:
          type: string
    KeyCodes:
      type: object
      properties:
        key_codes:
          type: array
          items:
            type: string
    Thread:
      type: object
      properties:
        guid:
          type: string
          format: uuid
        subject:
          type: string
        is_read:
          type: boolean
        is_archived:
          type: boolean
        messages:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                format: int32
              type:
                type: string
              subject:
                type: string
              message:
                type: string
              created_at:
                type: string
                format: date-time
    Webhook:
      type: object
      properties:
        id:
          type: string
        event:
          type: string
        target_url:
          type: string
          format: uri
    WebhookSubscribe:
      type: object
      required:
        - event
        - target_url
      properties:
        event:
          type: string
          description: Event name to subscribe to (for example, booking_change).
        target_url:
          type: string
          format: uri
          description: Unique URL called when the event occurs.
    WebhookUnsubscribe:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Identifier of the subscription to remove.
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string