{"openapi":"3.1.0","info":{"title":"Hostfully (BYOK) API","version":"0.1.0","description":"Hostfully (BYOK) lets an AI assistant read your own Hostfully data through the Hostfully API with a key you supply (Hostfully agency API key). Read-only: 9 tools (list_agencies, list_properties, get_property, get_property_calendar, list_pricing_periods, list_leads, list_reviews, get_review_statistics, list_property_rooms). The BYOK key travels with each request, is used for that one call only and...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hostfully.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hostfully/docs"},"termsOfService":"https://connectorbay.com/byok-hostfully/terms"},"servers":[{"url":"https://byok-hostfully.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hostfully/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_agencies":{"post":{"operationId":"list_agencies","summary":"List the Hostfully agencies the key can access with name, website, city, currency and default check-in and check-out hou","description":"List the Hostfully agencies the key can access with name, website, city, currency and default check-in and check-out hours. Use for \"Which Hostfully agency does my key belong to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_agenciesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_properties":{"post":{"operationId":"list_properties","summary":"List an agency's properties with address, type, bedrooms, beds, bathrooms, guest limits, minimum stay, daily rate and ac","description":"List an agency's properties with address, type, bedrooms, beds, bathrooms, guest limits, minimum stay, daily rate and active flag. Use for \"Which active properties does my agency manage and what is their daily rate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agency_uid":{"description":"Hostfully agency UID (from list_agencies).","maxLength":64,"title":"Agency Uid","type":"string"},"updated_since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only properties changed since this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated Since"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (maximum depends on the endpoint, 100 is safe).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's _paging._nextCursor to fetch the next page.","title":"Cursor"}},"required":["agency_uid"],"title":"list_propertiesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_property":{"post":{"operationId":"get_property","summary":"Get one property's details: address and coordinates, size, guest limits, stay rules, check-in window, pricing and fees, ","description":"Get one property's details: address and coordinates, size, guest limits, stay rules, check-in window, pricing and fees, cancellation policy and listing links. Access notes and Wi-Fi details are not returned. Use for \"What are the stay rules and fees for property a1b2c3d4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_uid":{"description":"Hostfully property UID.","maxLength":200,"title":"Property Uid","type":"string"}},"required":["property_uid"],"title":"get_propertyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_property_calendar":{"post":{"operationId":"get_property_calendar","summary":"Get a property's day-by-day calendar for a date range: nightly price, whether the day is unavailable and why, check-in a","description":"Get a property's day-by-day calendar for a date range: nightly price, whether the day is unavailable and why, check-in and check-out availability and minimum stay. Use for \"Which nights in December are still open at property a1b2c3d4 and at what price\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_uid":{"description":"Hostfully property UID.","maxLength":200,"title":"Property Uid","type":"string"},"from_date":{"description":"First day of the range, YYYY-MM-DD.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last day of the range, YYYY-MM-DD.","maxLength":10,"title":"To Date","type":"string"}},"required":["property_uid","from_date","to_date"],"title":"get_property_calendarArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_pricing_periods":{"post":{"operationId":"list_pricing_periods","summary":"List the date-based pricing periods of a property in a date range with price, minimum stay and check-in or check-out ava","description":"List the date-based pricing periods of a property in a date range with price, minimum stay and check-in or check-out availability. Use for \"What nightly prices are set for property a1b2c3d4 over New Year\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_uid":{"description":"Hostfully property UID (a UUID from list_properties).","maxLength":64,"title":"Property Uid","type":"string"},"from_date":{"description":"First day, YYYY-MM-DD.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"Last day, YYYY-MM-DD.","maxLength":10,"title":"To Date","type":"string"}},"required":["property_uid","from_date","to_date"],"title":"list_pricing_periodsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_leads":{"post":{"operationId":"list_leads","summary":"List reservations and inquiries (leads) with stay dates, status, type, channel and guest counts. One of property_uid or ","description":"List reservations and inquiries (leads) with stay dates, status, type, channel and guest counts. One of property_uid or agency_uid is required. Guest contact details are not returned. Use for \"Which bookings check in at property a1b2c3d4 in December\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_uid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only leads of this property UID.","title":"Property Uid"},"agency_uid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only leads of this agency UID.","title":"Agency Uid"},"check_in_from":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Check-in on or after this date, YYYY-MM-DD.","title":"Check In From"},"check_in_to":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Check-in on or before this date, YYYY-MM-DD.","title":"Check In To"},"updated_since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only leads changed since this ISO 8601 time.","title":"Updated Since"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (maximum depends on the endpoint, 100 is safe).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's _paging._nextCursor to fetch the next page.","title":"Cursor"}},"title":"list_leadsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_reviews":{"post":{"operationId":"list_reviews","summary":"List guest reviews of a property or reservation with rating, title, text, source (Booking.com, Vrbo, Tripadvisor, Hostfu","description":"List guest reviews of a property or reservation with rating, title, text, source (Booking.com, Vrbo, Tripadvisor, Hostfully ...), date and the host's reply. Use for \"What are the latest reviews of property a1b2c3d4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_uid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only reviews of this property UID.","title":"Property Uid"},"lead_uid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only reviews of this lead UID.","title":"Lead Uid"},"source":{"anyOf":[{"enum":["BOOKING_DOT_COM","VRBO","FACEBOOK","TRIPADVISOR","REVYOOS","HOSTFULLY"],"type":"string"},{"type":"null"}],"default":null,"description":"Review source.","title":"Source"},"sort":{"anyOf":[{"enum":["SORT_BY_RATING","SORT_BY_DATE","SORT_BY_AUTHOR"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by rating, date or author.","title":"Sort"},"sort_direction":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":null,"description":"ASC or DESC.","title":"Sort Direction"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (maximum depends on the endpoint, 100 is safe).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's _paging._nextCursor to fetch the next page.","title":"Cursor"}},"title":"list_reviewsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_review_statistics":{"post":{"operationId":"get_review_statistics","summary":"Get the number of reviews and the average rating of one property. Use for \"What is the average guest rating of property ","description":"Get the number of reviews and the average rating of one property. Use for \"What is the average guest rating of property a1b2c3d4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_uid":{"description":"Hostfully property UID (a UUID from list_properties).","maxLength":64,"title":"Property Uid","type":"string"}},"required":["property_uid"],"title":"get_review_statisticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_property_rooms":{"post":{"operationId":"list_property_rooms","summary":"List the rooms of a property with room number, type, private bathroom flag and bed counts by bed type. Use for \"How many","description":"List the rooms of a property with room number, type, private bathroom flag and bed counts by bed type. Use for \"How many beds and bathrooms does each room of property a1b2c3d4 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_uid":{"description":"Hostfully property UID (a UUID from list_properties).","maxLength":64,"title":"Property Uid","type":"string"}},"required":["property_uid"],"title":"list_property_roomsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}