Hostaway MCP Server

openapi: 3.1.0 info: title: Hostaway Bookings API description: Reservation management endpoints for searching, retrieving, and managing bookings version: 1.0.0 contact: name: Hostaway API Support url: https://api.hostaway.com/documentation servers: - url: https://api.hostaway.com/v1 description: Hostaway Production API security: - bearerAuth: [] paths: /reservations: get: operationId: searchBookings summary: Search bookings with filters description: | Search and filter reservations based on date range, property, status, and other criteria. Results are paginated with a default limit of 100 items per page. Rate Limits: - 15 requests per 10 seconds per IP address - 20 requests per 10 seconds per account tags: - Bookings parameters: - name: limit in: query description: Maximum number of results per page schema: type: integer minimum: 1 maximum: 100 default: 100 example: 50 - name: offset in: query description: Number of results to skip for pagination schema: type: integer minimum: 0 default: 0 example: 0 - name: listingId in: query description: Filter by specific property ID schema: type: integer example: 12345 - name: status in: query description: Filter by reservation status schema: type: string enum: [new, modified, cancelled, inquiry, reserved, confirmed] example: confirmed - name: arrivalStartDate in: query description: Filter reservations with check-in on or after this date (YYYY-MM-DD) schema: type: string format: date example: "2025-01-01" - name: arrivalEndDate in: query description: Filter reservations with check-in on or before this date (YYYY-MM-DD) schema: type: string format: date example: "2025-01-31" - name: departureStartDate in: query description: Filter reservations with check-out on or after this date (YYYY-MM-DD) schema: type: string format: date example: "2025-01-01" - name: departureEndDate in: query description: Filter reservations with check-out on or before this date (YYYY-MM-DD) schema: type: string format: date example: "2025-01-31" - name: guestName in: query description: Filter by guest name (partial match) schema: type: string example: "John Doe" - name: channelId in: query description: Filter by booking source/channel schema: type: string enum: [airbnb, vrbo, bookingCom, direct] example: airbnb - name: sortOrder in: query description: Sort direction by check-in date schema: type: string enum: [asc, desc] default: asc example: desc responses: '200': description: Successfully retrieved bookings content: application/json: schema: $ref: '#/components/schemas/BookingsResponse' examples: success: value: status: "success" result: - id: 67890 listingId: 12345 listingName: "Beautiful Beachfront Villa" guestId: 11111 guestName: "John Doe" guestEmail: "john.doe@example.com" checkInDate: "2025-01-15" checkOutDate: "2025-01-20" guests: 4 status: "confirmed" totalPrice: 2150 channelId: "airbnb" - id: 67891 listingId: 12345 listingName: "Beautiful Beachfront Villa" guestId: 11112 guestName: "Jane Smith" guestEmail: "jane.smith@example.com" checkInDate: "2025-01-22" checkOutDate: "2025-01-25" guests: 2 status: "confirmed" totalPrice: 1350 channelId: "direct" count: 2 limit: 100 offset: 0 '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidDateRange: value: status: "error" message: "End date must be after start date" code: "INVALID_DATE_RANGE" '401': description: Unauthorized - invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /reservations/{id}: get: operationId: getBookingDetails summary: Get booking details description: | Retrieve comprehensive details for a specific reservation including guest information, payment status, pricing breakdown, and special requests. tags: - Bookings parameters: - name: id in: path required: true description: Unique identifier for the reservation schema: type: integer example: 67890 responses: '200': description: Successfully retrieved booking details content: application/json: schema: $ref: '#/components/schemas/BookingDetailsResponse' examples: success: value: status: "success" result: id: 67890 listingId: 12345 listingName: "Beautiful Beachfront Villa" guestId: 11111 guestName: "John Doe" guestEmail: "john.doe@example.com" guestPhone: "+1-555-0100" checkInDate: "2025-01-15" checkOutDate: "2025-01-20" checkInTime: "15:00" checkOutTime: "11:00" nights: 5 guests: 4 adults: 2 children: 2 status: "confirmed" channelId: "airbnb" channelReservationId: "HMABCD123456" createdAt: "2024-12-01T10:30:00Z" updatedAt: "2024-12-01T10:30:00Z" pricing: basePrice: 350 nightlyRate: 350 totalNights: 1750 cleaningFee: 150 serviceFee: 125 taxes: 125 totalPrice: 2150 currency: "USD" paymentStatus: "paid" specialRequests: "Early check-in requested" internalNotes: "VIP guest - anniversary celebration" cancellationPolicy: "moderate" isPaid: true paymentMethod: "credit_card" '401': description: Unauthorized - invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Booking not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: value: status: "error" message: "Reservation with ID 67890 not found" code: "NOT_FOUND" '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /reservations/{id}/guest: get: operationId: getBookingGuestInfo summary: Get guest information for booking description: | Retrieve detailed guest contact information and preferences associated with a reservation. This includes email, phone, communication preferences, and booking history. tags: - Bookings parameters: - name: id in: path required: true description: Unique identifier for the reservation schema: type: integer example: 67890 responses: '200': description: Successfully retrieved guest information content: application/json: schema: $ref: '#/components/schemas/GuestInfoResponse' examples: success: value: status: "success" result: guestId: 11111 firstName: "John" lastName: "Doe" fullName: "John Doe" email: "john.doe@example.com" phone: "+1-555-0100" preferredLanguage: "en" communicationChannel: "email" address: street: "789 Main Street" city: "Los Angeles" state: "CA" zipCode: "90001" country: "United States" emergencyContact: name: "Jane Doe" phone: "+1-555-0101" relationship: "spouse" bookingHistory: totalBookings: 3 totalNights: 15 totalSpent: 5250 firstBooking: "2023-06-15" lastBooking: "2024-12-01" preferences: specialDietaryNeeds: "vegetarian" bedPreference: "king" smokingPreference: "non-smoking" verifications: emailVerified: true phoneVerified: true idVerified: true '401': description: Unauthorized - invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Booking or guest not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: value: status: "error" message: "Guest information not found for reservation 67890" code: "NOT_FOUND" '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth 2.0 access token obtained from /v1/accessTokens schemas: BookingsResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: type: array description: Array of reservation summaries items: $ref: '#/components/schemas/BookingSummary' count: type: integer description: Number of results returned example: 2 limit: type: integer description: Maximum results per page example: 100 offset: type: integer description: Pagination offset example: 0 BookingSummary: type: object required: - id - listingId - guestName - checkInDate - checkOutDate - status properties: id: type: integer description: Unique reservation identifier example: 67890 listingId: type: integer description: Associated property ID example: 12345 listingName: type: string description: Property name example: "Beautiful Beachfront Villa" guestId: type: integer description: Guest identifier example: 11111 guestName: type: string description: Guest full name example: "John Doe" guestEmail: type: string format: email description: Guest email address example: "john.doe@example.com" checkInDate: type: string format: date description: Check-in date example: "2025-01-15" checkOutDate: type: string format: date description: Check-out date example: "2025-01-20" guests: type: integer description: Total number of guests example: 4 status: type: string enum: [new, modified, cancelled, inquiry, reserved, confirmed] description: Reservation status example: "confirmed" totalPrice: type: number format: float description: Total booking price example: 2150 channelId: type: string description: Booking source/channel example: "airbnb" BookingDetailsResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: $ref: '#/components/schemas/BookingDetails' BookingDetails: allOf: - $ref: '#/components/schemas/BookingSummary' - type: object properties: guestPhone: type: string description: Guest phone number example: "+1-555-0100" checkInTime: type: string format: time description: Check-in time (HH:MM) example: "15:00" checkOutTime: type: string format: time description: Check-out time (HH:MM) example: "11:00" nights: type: integer description: Number of nights example: 5 adults: type: integer description: Number of adult guests example: 2 children: type: integer description: Number of child guests example: 2 channelReservationId: type: string description: External channel booking ID example: "HMABCD123456" createdAt: type: string format: date-time description: Booking creation timestamp example: "2024-12-01T10:30:00Z" updatedAt: type: string format: date-time description: Last update timestamp example: "2024-12-01T10:30:00Z" pricing: $ref: '#/components/schemas/PricingBreakdown' specialRequests: type: string description: Guest special requests example: "Early check-in requested" internalNotes: type: string description: Internal property manager notes example: "VIP guest - anniversary celebration" cancellationPolicy: type: string description: Applied cancellation policy example: "moderate" isPaid: type: boolean description: Payment completion status example: true paymentMethod: type: string description: Payment method used example: "credit_card" PricingBreakdown: type: object properties: basePrice: type: number format: float description: Base nightly rate example: 350 nightlyRate: type: number format: float description: Average nightly rate (may vary by date) example: 350 totalNights: type: number format: float description: Total for all nights example: 1750 cleaningFee: type: number format: float description: One-time cleaning fee example: 150 serviceFee: type: number format: float description: Service/booking fee example: 125 taxes: type: number format: float description: Total taxes example: 125 totalPrice: type: number format: float description: Final total price example: 2150 currency: type: string description: Currency code (ISO 4217) example: "USD" paymentStatus: type: string enum: [pending, partial, paid, refunded] description: Payment status example: "paid" GuestInfoResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: $ref: '#/components/schemas/GuestInfo' GuestInfo: type: object required: - guestId - firstName - lastName - email properties: guestId: type: integer description: Unique guest identifier example: 11111 firstName: type: string description: Guest first name example: "John" lastName: type: string description: Guest last name example: "Doe" fullName: type: string description: Guest full name example: "John Doe" email: type: string format: email description: Guest email address example: "john.doe@example.com" phone: type: string description: Guest phone number example: "+1-555-0100" preferredLanguage: type: string description: Preferred language code (ISO 639-1) example: "en" communicationChannel: type: string enum: [email, sms, whatsapp, platform] description: Preferred communication method example: "email" address: $ref: '#/components/schemas/Address' emergencyContact: $ref: '#/components/schemas/EmergencyContact' bookingHistory: $ref: '#/components/schemas/BookingHistory' preferences: $ref: '#/components/schemas/GuestPreferences' verifications: $ref: '#/components/schemas/GuestVerifications' Address: type: object properties: street: type: string example: "789 Main Street" city: type: string example: "Los Angeles" state: type: string example: "CA" zipCode: type: string example: "90001" country: type: string example: "United States" EmergencyContact: type: object properties: name: type: string example: "Jane Doe" phone: type: string example: "+1-555-0101" relationship: type: string example: "spouse" BookingHistory: type: object properties: totalBookings: type: integer description: Total number of bookings example: 3 totalNights: type: integer description: Total nights stayed example: 15 totalSpent: type: number format: float description: Total amount spent example: 5250 firstBooking: type: string format: date description: Date of first booking example: "2023-06-15" lastBooking: type: string format: date description: Date of most recent booking example: "2024-12-01" GuestPreferences: type: object properties: specialDietaryNeeds: type: string example: "vegetarian" bedPreference: type: string example: "king" smokingPreference: type: string enum: [smoking, non-smoking] example: "non-smoking" GuestVerifications: type: object properties: emailVerified: type: boolean example: true phoneVerified: type: boolean example: true idVerified: type: boolean example: true ErrorResponse: type: object required: - status - message properties: status: type: string enum: [error] description: Error status indicator message: type: string description: Human-readable error message example: "Invalid access token" code: type: string description: Machine-readable error code example: "UNAUTHORIZED" details: type: object description: Additional error context additionalProperties: true tags: - name: Bookings description: Reservation management operations for searching, retrieving, and managing bookings