{"openapi":"3.1.0","info":{"title":"Beds24 (BYOK) API","version":"0.1.0","description":"Beds24 (BYOK) lets an AI assistant read your own Beds24 data through the Beds24 API with a key you supply (Beds24 long life token). Read-only: 9 tools (get_token_details, list_bookings, search_bookings, get_booking, list_properties, get_room_availability, get_calendar, list_messages, get_offers). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-beds24.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-beds24/docs"},"termsOfService":"https://connectorbay.com/byok-beds24/terms"},"servers":[{"url":"https://byok-beds24.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-beds24/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/get_token_details":{"post":{"operationId":"get_token_details","summary":"Show whether the token is valid, its owner id, creation time and scope-related settings. Use for \"Is my Beds24 API token","description":"Show whether the token is valid, its owner id, creation time and scope-related settings. Use for \"Is my Beds24 API token valid and when was it created\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_token_detailsArguments","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_bookings":{"post":{"operationId":"list_bookings","summary":"List bookings (upcoming confirmed, request, new, black and inquiry bookings by default) with dates, guest name, status, ","description":"List bookings (upcoming confirmed, request, new, black and inquiry bookings by default) with dates, guest name, status, channel and price; filter by arrivals, departures, property, room or a date range. Use for \"Which Beds24 bookings arrive this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"enum":["arrivals","departures","new","current"],"type":"string"},{"type":"null"}],"default":null,"description":"Quick filter: arrivals (today), departures (today), new, or current.","title":"Filter"},"property_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 property id.","title":"Property Id"},"room_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 room id.","title":"Room Id"},"arrival_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only bookings arriving after this date, YYYY-MM-DD.","title":"Arrival From"},"arrival_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only bookings arriving before this date, YYYY-MM-DD.","title":"Arrival To"},"departure_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only bookings departing after this date, YYYY-MM-DD.","title":"Departure From"},"departure_to":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only bookings departing before this date, YYYY-MM-DD.","title":"Departure To"},"status":{"anyOf":[{"enum":["confirmed","request","new","cancelled","black","inquiry"],"type":"string"},{"type":"null"}],"default":null,"description":"Only bookings with this status.","title":"Status"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (the answer says whether a next page exists).","title":"Page"}},"title":"list_bookingsArguments","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/search_bookings":{"post":{"operationId":"search_bookings","summary":"Find bookings whose guest name, e-mail, API reference or booking id matches a text. Use for \"Find the Beds24 booking for","description":"Find bookings whose guest name, e-mail, API reference or booking id matches a text. Use for \"Find the Beds24 booking for guest Smith\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_string":{"description":"Text matched against guest name, e-mail, API reference and booking id.","maxLength":100,"title":"Search String","type":"string"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (the answer says whether a next page exists).","title":"Page"}},"required":["search_string"],"title":"search_bookingsArguments","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_booking":{"post":{"operationId":"get_booking","summary":"Get one booking by its numeric id, including cancelled ones. Use for \"Show Beds24 booking 123456\".","description":"Get one booking by its numeric id, including cancelled ones. Use for \"Show Beds24 booking 123456\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Beds24 booking id.","minimum":1,"title":"Id","type":"integer"},"status":{"anyOf":[{"enum":["confirmed","request","new","cancelled","black","inquiry"],"type":"string"},{"type":"null"}],"default":null,"description":"Set to cancelled to find a cancelled booking (cancelled bookings are hidden by default).","title":"Status"}},"required":["id"],"title":"get_bookingArguments","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 the properties of the account with name, type, currency, address, country and check-in and check-out times. Use for","description":"List the properties of the account with name, type, currency, address, country and check-in and check-out times. Use for \"What properties are in my Beds24 account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this property id.","title":"Id"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (the answer says whether a next page exists).","title":"Page"}},"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_room_availability":{"post":{"operationId":"get_room_availability","summary":"Show per-date availability of rooms for a date range (the data holds a date to available map per room). Use for \"Which B","description":"Show per-date availability of rooms for a date range (the data holds a date to available map per room). Use for \"Which Beds24 rooms are free next weekend\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"property_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 property id.","title":"Property Id"},"room_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 room id.","title":"Room Id"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First date, YYYY-MM-DD.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last night to be booked (the day before check-out), YYYY-MM-DD.","title":"End Date"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (the answer says whether a next page exists).","title":"Page"}},"title":"get_room_availabilityArguments","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_calendar":{"post":{"operationId":"get_calendar","summary":"Get per-day calendar values for rooms between two dates: availability count, minimum stay and prices when asked for. Use","description":"Get per-day calendar values for rooms between two dates: availability count, minimum stay and prices when asked for. Use for \"What are my Beds24 nightly prices for next month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_date":{"description":"First date, YYYY-MM-DD.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"Last date, YYYY-MM-DD.","maxLength":200,"title":"End Date","type":"string"},"property_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 property id.","title":"Property Id"},"room_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 room id.","title":"Room Id"},"include_num_avail":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to include the number of rooms available per day.","title":"Include Num Avail"},"include_min_stay":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include the minimum stay per day.","title":"Include Min Stay"},"include_prices":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to include price fields per day.","title":"Include Prices"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (the answer says whether a next page exists).","title":"Page"}},"required":["start_date","end_date"],"title":"get_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_messages":{"post":{"operationId":"list_messages","summary":"List guest and host messages of bookings with booking id, source, text, read flag and time. Use for \"Which Beds24 guest ","description":"List guest and host messages of bookings with booking id, source, text, read flag and time. Use for \"Which Beds24 guest messages are unread\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"booking_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only messages of this booking id.","title":"Booking Id"},"property_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 property id.","title":"Property Id"},"filter":{"anyOf":[{"enum":["read","unread"],"type":"string"},{"type":"null"}],"default":null,"description":"Only read or unread messages.","title":"Filter"},"source":{"anyOf":[{"enum":["host","guest","internalNote","system"],"type":"string"},{"type":"null"}],"default":null,"description":"Only messages from this side of the conversation.","title":"Source"},"max_age":{"anyOf":[{"maximum":999,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only messages newer than this many days (1 to 999).","title":"Max Age"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (the answer says whether a next page exists).","title":"Page"}},"title":"list_messagesArguments","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_offers":{"post":{"operationId":"get_offers","summary":"Get priced offers for stays: for each room the offers available for arrival and departure dates and a number of adults. ","description":"Get priced offers for stays: for each room the offers available for arrival and departure dates and a number of adults. Use for \"What can a couple book at my Beds24 property from 1 to 5 December\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"arrival":{"description":"Arrival date, YYYY-MM-DD.","maxLength":200,"title":"Arrival","type":"string"},"departure":{"description":"Departure date, YYYY-MM-DD.","maxLength":200,"title":"Departure","type":"string"},"num_adults":{"description":"Number of adults.","maximum":50,"minimum":1,"title":"Num Adults","type":"integer"},"num_children":{"anyOf":[{"maximum":50,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of children.","title":"Num Children"},"property_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 property id.","title":"Property Id"},"room_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this Beds24 room id.","title":"Room Id"},"page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number of results, starting at 1 (the answer says whether a next page exists).","title":"Page"}},"required":["arrival","departure","num_adults"],"title":"get_offersArguments","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}}}}