Hostaway MCP Server

openapi: 3.1.0 info: title: Hostaway Listings API description: Property management endpoints for listing properties, details, and availability 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: /listings: get: operationId: listProperties summary: List all properties description: | Retrieve a list of all properties managed in the Hostaway account. 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: - Listings 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: sortOrder in: query description: Sort direction schema: type: string enum: [asc, desc] default: asc example: asc - name: city in: query description: Filter by city name schema: type: string example: "San Francisco" - name: status in: query description: Filter by listing status schema: type: string enum: [active, inactive, archived] example: active responses: '200': description: Successfully retrieved listings content: application/json: schema: $ref: '#/components/schemas/ListingsResponse' examples: success: value: status: "success" result: - id: 12345 name: "Beautiful Beachfront Villa" address: "123 Ocean Drive, San Francisco, CA 94016" city: "San Francisco" capacity: 8 bedrooms: 4 bathrooms: 3.5 status: "active" - id: 12346 name: "Downtown Modern Apartment" address: "456 Market Street, San Francisco, CA 94102" city: "San Francisco" capacity: 4 bedrooms: 2 bathrooms: 2 status: "active" count: 2 limit: 100 offset: 0 '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' /listings/{id}: get: operationId: getPropertyDetails summary: Get property details description: | Retrieve comprehensive details for a specific property including amenities, pricing, capacity, images, and channel integrations. tags: - Listings parameters: - name: id in: path required: true description: Unique identifier for the property schema: type: integer example: 12345 responses: '200': description: Successfully retrieved property details content: application/json: schema: $ref: '#/components/schemas/PropertyDetailsResponse' examples: success: value: status: "success" result: id: 12345 name: "Beautiful Beachfront Villa" address: "123 Ocean Drive" city: "San Francisco" state: "CA" zipCode: "94016" country: "United States" latitude: 37.7749 longitude: -122.4194 description: "Stunning oceanfront property with panoramic views" capacity: 8 bedrooms: 4 bathrooms: 3.5 accommodationType: "Entire home/apt" status: "active" amenities: - "WiFi" - "Kitchen" - "Parking" - "Pool" - "Air conditioning" - "Ocean view" pricing: currency: "USD" basePrice: 350 weekendPrice: 450 cleaningFee: 150 securityDeposit: 500 images: - "https://cdn.hostaway.com/images/listing-12345-1.jpg" - "https://cdn.hostaway.com/images/listing-12345-2.jpg" channelIds: airbnb: "airbnb-listing-123" vrbo: "vrbo-listing-456" bookingCom: "booking-listing-789" cancellationPolicy: "moderate" checkInTime: "15:00" checkOutTime: "11:00" '401': description: Unauthorized - invalid or missing access token content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Property not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: notFound: value: status: "error" message: "Listing with ID 12345 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' /listings/{id}/calendar: get: operationId: getPropertyAvailability summary: Check property availability description: | Retrieve calendar availability for a specific property within a date range. Shows available dates, blocked dates, and existing reservations. tags: - Listings parameters: - name: id in: path required: true description: Unique identifier for the property schema: type: integer example: 12345 - name: startDate in: query required: true description: Start date for availability check (YYYY-MM-DD) schema: type: string format: date example: "2025-01-01" - name: endDate in: query required: true description: End date for availability check (YYYY-MM-DD) schema: type: string format: date example: "2025-01-31" responses: '200': description: Successfully retrieved availability calendar content: application/json: schema: $ref: '#/components/schemas/AvailabilityResponse' examples: success: value: status: "success" result: listingId: 12345 startDate: "2025-01-01" endDate: "2025-01-31" calendar: - date: "2025-01-01" status: "available" price: 350 minimumStay: 2 - date: "2025-01-02" status: "available" price: 350 minimumStay: 2 - date: "2025-01-03" status: "booked" reservationId: 67890 price: 350 - date: "2025-01-04" status: "blocked" reason: "maintenance" - date: "2025-01-05" status: "available" price: 450 minimumStay: 2 '400': description: Invalid date range or 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' '404': description: Property not found 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' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth 2.0 access token obtained from /v1/accessTokens schemas: ListingsResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: type: array description: Array of property listings items: $ref: '#/components/schemas/ListingSummary' 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 ListingSummary: type: object required: - id - name - address properties: id: type: integer description: Unique property identifier example: 12345 name: type: string description: Property name/title example: "Beautiful Beachfront Villa" address: type: string description: Full property address example: "123 Ocean Drive, San Francisco, CA 94016" city: type: string description: City name example: "San Francisco" capacity: type: integer description: Maximum guest capacity example: 8 bedrooms: type: integer description: Number of bedrooms example: 4 bathrooms: type: number format: float description: Number of bathrooms (can include half baths) example: 3.5 status: type: string enum: [active, inactive, archived] description: Current listing status example: "active" thumbnailUrl: type: string format: uri description: URL to property thumbnail image example: "https://cdn.hostaway.com/images/listing-12345-thumb.jpg" PropertyDetailsResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: $ref: '#/components/schemas/PropertyDetails' PropertyDetails: allOf: - $ref: '#/components/schemas/ListingSummary' - type: object properties: state: type: string description: State/province example: "CA" zipCode: type: string description: Postal/ZIP code example: "94016" country: type: string description: Country name example: "United States" latitude: type: number format: double description: Geographic latitude example: 37.7749 longitude: type: number format: double description: Geographic longitude example: -122.4194 description: type: string description: Full property description example: "Stunning oceanfront property with panoramic views" accommodationType: type: string description: Type of accommodation example: "Entire home/apt" amenities: type: array description: List of property amenities items: type: string example: ["WiFi", "Kitchen", "Parking", "Pool"] pricing: $ref: '#/components/schemas/PricingInfo' images: type: array description: URLs to property images items: type: string format: uri example: ["https://cdn.hostaway.com/images/listing-12345-1.jpg"] channelIds: type: object description: External channel listing IDs additionalProperties: type: string example: airbnb: "airbnb-listing-123" vrbo: "vrbo-listing-456" cancellationPolicy: type: string description: Cancellation policy type example: "moderate" checkInTime: type: string format: time description: Default check-in time (HH:MM) example: "15:00" checkOutTime: type: string format: time description: Default check-out time (HH:MM) example: "11:00" PricingInfo: type: object properties: currency: type: string description: Currency code (ISO 4217) example: "USD" basePrice: type: number format: float description: Base nightly rate example: 350 weekendPrice: type: number format: float description: Weekend nightly rate example: 450 cleaningFee: type: number format: float description: Cleaning fee per booking example: 150 securityDeposit: type: number format: float description: Security deposit amount example: 500 AvailabilityResponse: type: object required: - status - result properties: status: type: string enum: [success] description: Response status result: $ref: '#/components/schemas/AvailabilityCalendar' AvailabilityCalendar: type: object required: - listingId - startDate - endDate - calendar properties: listingId: type: integer description: Property identifier example: 12345 startDate: type: string format: date description: Calendar start date example: "2025-01-01" endDate: type: string format: date description: Calendar end date example: "2025-01-31" calendar: type: array description: Daily availability entries items: $ref: '#/components/schemas/CalendarDay' CalendarDay: type: object required: - date - status properties: date: type: string format: date description: Calendar date example: "2025-01-01" status: type: string enum: [available, booked, blocked] description: Availability status example: "available" price: type: number format: float description: Nightly price for this date example: 350 minimumStay: type: integer description: Minimum stay requirement in nights example: 2 reservationId: type: integer description: Associated reservation ID (if booked) example: 67890 reason: type: string description: Reason for blocking (if blocked) example: "maintenance" 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: Listings description: Property management operations for listings, details, and availability