{"openapi":"3.1.0","info":{"title":"Xola (BYOK) API","version":"0.1.0","description":"Xola (BYOK) lets an AI assistant read your own Xola data through the Xola API with a key you supply (Xola API key). Read-only: 9 tools (get_current_user, list_experiences, get_experience, get_upcoming_dates, list_timeslots, list_events, list_purchases, list_coupons, get_transactions_summary). 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-xola.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-xola/docs"},"termsOfService":"https://connectorbay.com/byok-xola/terms"},"servers":[{"url":"https://byok-xola.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-xola/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_current_user":{"post":{"operationId":"get_current_user","summary":"Show the Xola account the key belongs to: id, name, account type and whether it is enabled. Use the id as the seller in ","description":"Show the Xola account the key belongs to: id, name, account type and whether it is enabled. Use the id as the seller in other tools. Use for \"Which Xola account is my key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_userArguments","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_experiences":{"post":{"operationId":"list_experiences","summary":"List experiences (tours and activities) with name, price, currency, status, excerpt and group size limits. Filter by sel","description":"List experiences (tours and activities) with name, price, currency, status, excerpt and group size limits. Filter by seller, category, name text or location. Use for \"Which experiences does my Xola account offer and what do they cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seller":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Xola seller (account) id; see get_current_user.","title":"Seller"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Search experiences by name.","title":"Name"},"category":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Filter by category name.","title":"Category"},"geo":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Location filter as 'lat,lng' or 'lat,lng,radius_km'.","title":"Geo"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Skip"}},"title":"list_experiencesArguments","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_experience":{"post":{"operationId":"get_experience","summary":"Get one experience with description, price, currency, status, cancellation policy and group limits. Use for \"Give me the","description":"Get one experience with description, price, currency, status, cancellation policy and group limits. Use for \"Give me the full details of Xola experience exp1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"experience_id":{"description":"Xola experience id (from list_experiences).","maxLength":40,"title":"Experience Id","type":"string"}},"required":["experience_id"],"title":"get_experienceArguments","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_upcoming_dates":{"post":{"operationId":"get_upcoming_dates","summary":"List the upcoming dates on which an experience has availability, optionally for a minimum number of seats and from a sta","description":"List the upcoming dates on which an experience has availability, optionally for a minimum number of seats and from a start date. Use for \"On which dates is experience exp1 available for 4 guests\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"experience_id":{"description":"Xola experience id.","maxLength":40,"title":"Experience Id","type":"string"},"quantity":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Minimum number of seats that must be free.","title":"Quantity"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Search from this date, YYYY-MM-DD.","title":"Start Date"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Maximum number of dates to return.","title":"Limit"}},"required":["experience_id"],"title":"get_upcoming_datesArguments","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_timeslots":{"post":{"operationId":"list_timeslots","summary":"List bookable timeslots with date, time, open and maximum capacity, privacy, unit prices and whether booking or waitlist","description":"List bookable timeslots with date, time, open and maximum capacity, privacy, unit prices and whether booking or waitlisting is possible. Use for \"What timeslots with free seats does experience exp1 have in November\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Experience id(s), comma-separated.","title":"Product"},"seller":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Xola seller (account) id; see get_current_user.","title":"Seller"},"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start date YYYY-MM-DD (or a range as documented by Xola).","title":"Start"},"end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"End date YYYY-MM-DD, used with start.","title":"End"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA time zone name, for example America/Los_Angeles.","title":"Timezone"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many timeslots to return (1 to 100).","title":"Limit"}},"title":"list_timeslotsArguments","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_events":{"post":{"operationId":"list_events","summary":"List scheduled events (departures) with start, end, title, open seats, reserved, confirmed and pending guest counts, pri","description":"List scheduled events (departures) with start, end, title, open seats, reserved, confirmed and pending guest counts, privacy and assigned guides. Use for \"How full are my tours next week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seller":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this seller id.","title":"Seller"},"experience":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this experience id.","title":"Experience"},"start":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Start of the range as a Unix timestamp in seconds.","title":"Start"},"end":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"End of the range as a Unix timestamp in seconds.","title":"End"},"closed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include closed events.","title":"Closed"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Skip"}},"title":"list_eventsArguments","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_purchases":{"post":{"operationId":"list_purchases","summary":"List bookings (purchases) with status, customer name, amount, balance, currency and source. Email and phone are not retu","description":"List bookings (purchases) with status, customer name, amount, balance, currency and source. Email and phone are not returned. Filter by seller, status or text. Use for \"Which Xola bookings still have a balance due\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seller":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only purchases of this seller id.","title":"Seller"},"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text to search in customer names and purchase details.","title":"Search"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field; prefix with - for descending, for example -createdAt.","title":"Sort"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Number of results per page (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip.","title":"Offset"}},"title":"list_purchasesArguments","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_coupons":{"post":{"operationId":"list_coupons","summary":"List coupons with name, type, discount algorithm and amount, usage limit, source and the experiences they cover. Needs a","description":"List coupons with name, type, discount algorithm and amount, usage limit, source and the experiences they cover. Needs a seller or an experience id. Use for \"What discount coupons are active in my Xola account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seller":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Xola seller (account) id; see get_current_user.","title":"Seller"},"experience":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Experience id to filter by (alternative to seller).","title":"Experience"},"code":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"A specific coupon code.","title":"Code"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many results to return (1 to 100).","title":"Limit"},"skip":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many results to skip, for paging.","title":"Skip"}},"title":"list_couponsArguments","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_transactions_summary":{"post":{"operationId":"get_transactions_summary","summary":"Summarise transactions: total amount, seller earnings, count, average amount and breakdowns by type and payment method. ","description":"Summarise transactions: total amount, seller earnings, count, average amount and breakdowns by type and payment method. Use for \"How much did my Xola account earn in total\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"seller":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Xola seller (account) id; see get_current_user.","title":"Seller"}},"title":"get_transactions_summaryArguments","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}}}}