{ "openapi": "3.1.0", "info": { "title": "Stays Perks — Agent API", "version": "1.0.0", "description": "Stays Perks: Virtuoso hotel perks for AI agents. Search 2,000+ Virtuoso preferred hotels (live amenity data), create bookings, and pay autonomously via MPP (Tempo, pathUSD) or x402 (Base, USDC) — or hand off to a human advisor via the enquiry endpoint. Same rates as booking direct; Virtuoso perks (breakfast, upgrades, credits) included. An MCP server with equivalent tools runs at /mcp (Streamable HTTP; manifest at /.well-known/mcp.json). Guide for LLMs: /llms.txt. Bookings above auto-fulfill thresholds route to human advisor review; poll booking status for the outcome.", "contact": { "name": "Stays Perks (operated by Geisel Power Travel)", "email": "hello@powergtravel.com", "url": "https://staysperks.com/agent-hub.html" } }, "servers": [ { "url": "https://staysperks.com", "description": "Production" }, { "url": "https://geisel.vercel.app", "description": "Production (platform alias — same deployment)" } ], "paths": { "/api/catalog/search": { "get": { "operationId": "searchCatalog", "summary": "Search Virtuoso inventory (hotels, packages, cruises, services)", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text query: city, property name, or region (e.g. \"Paris\", \"Maldives\")" }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "hotels", "packages", "cruises", "services" ], "default": "hotels" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "default": 24 } }, { "name": "experience", "in": "query", "schema": { "type": "string" }, "description": "Experience facet filter (e.g. Beach, Wellness, Seclusion)" }, { "name": "region", "in": "query", "schema": { "type": "string" } }, { "name": "benefits", "in": "query", "schema": { "type": "string", "enum": [ "true" ] }, "description": "Only properties with published Virtuoso benefits" } ], "responses": { "200": { "description": "Ranked results from the live catalogue mirror (typically <150ms). Each result carries a trip_id usable with the booking endpoints.", "content": { "application/json": { "schema": { "type": "object" } } } }, "503": { "description": "Catalogue unavailable on this deployment" } } } }, "/api/catalog/property": { "get": { "operationId": "getProperty", "summary": "Full detail for one property (amenities, Virtuoso benefits)", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "virtuoso_property_id from a search result" } ], "responses": { "200": { "description": "Property detail" }, "400": { "description": "id missing" }, "404": { "description": "Unknown property" } } } }, "/api/catalog/themes": { "get": { "operationId": "listThemes", "summary": "Available experience/region facets with inventory counts", "responses": { "200": { "description": "Facet list" } } } }, "/api/agent-booking/create": { "post": { "operationId": "createBooking", "summary": "Create a booking (step 1 of 2)", "description": "Returns a booking with a pay endpoint when the trip auto-fulfills, or routes to human advisor review (poll status). Unpriced trips always go to advisor review — rates are quoted by the advisor.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "trip_id", "traveler_info" ], "properties": { "trip_id": { "type": "string", "description": "From catalog search results" }, "tier": { "type": "string", "description": "Membership tier if the traveler is a member" }, "num_nights": { "type": "integer" }, "agent_wallet_address": { "type": "string", "description": "Paying wallet (for refunds/receipts)" }, "traveler_info": { "type": "object", "required": [ "full_name", "email", "num_travelers" ], "properties": { "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "num_travelers": { "type": "integer" }, "phone": { "type": "string" } } } } } } } }, "responses": { "201": { "description": "Booking created — response includes booking_id, status, and pay_endpoint when auto-fulfillable" }, "404": { "description": "trip_not_found" }, "422": { "description": "traveler_info validation errors" } } } }, "/api/agent-booking/pay": { "post": { "operationId": "payBooking", "summary": "Settle a booking (step 2 of 2) — MPP, x402, or Stripe", "description": "Preferred rail: MPP on Tempo (chain 4217, pathUSD, sub-second finality) via `Authorization: Payment `. Also accepted: x402 via `X-PAYMENT-RECEIPT` header (USDC on Base, eip155:8453). Settlement is verified on-chain with replay protection before the booking confirms. Without a payment credential the response describes the required payment (402 semantics). Discovery: GET /api/mpp-info and /api/x402-info.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "booking_id" ], "properties": { "booking_id": { "type": "string" }, "payment_intent_id": { "type": "string", "description": "Stripe rail only" } } } } } }, "responses": { "200": { "description": "Payment verified — booking confirmed" }, "402": { "description": "Payment required — body carries the challenge/quote" }, "409": { "description": "Booking not in payment_processing state" }, "404": { "description": "Booking not found" } } } }, "/api/agent-booking/status/{id}": { "get": { "operationId": "getBookingStatus", "summary": "Booking status (unauthenticated; returns non-identifying fields only)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "status, review outcome, refund state" }, "404": { "description": "Not found" } } } }, "/api/agent-booking/cancel": { "post": { "operationId": "cancelBooking", "summary": "Cancel a booking (refund marked pending when paid)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "booking_id" ], "properties": { "booking_id": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Cancelled" }, "409": { "description": "Already cancelled/declined" }, "404": { "description": "Not found" } } } }, "/api/contact": { "post": { "operationId": "createEnquiry", "summary": "Start a human-advisor enquiry on the traveler's behalf", "description": "The concierge path: a human Virtuoso advisor replies within 24 hours with a quote and itinerary help. Ideal when the trip is complex, unpriced, or the traveler wants a person. Rate-limited.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "firstName", "lastName", "email", "dreamTrip" ], "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "tripType": { "type": "string" }, "destinations": { "type": "string" }, "travelDates": { "type": "string" }, "travelers": { "type": "string" }, "budget": { "type": "string" }, "dreamTrip": { "type": "string", "description": "Free-text description of the trip the traveler wants" }, "source": { "type": "string", "description": "Identify your agent platform here, e.g. \"muse-agent\"" } } } } } }, "responses": { "200": { "description": "Enquiry stored — response carries a quotable reference (LEAD-...)" }, "400": { "description": "Missing required fields" } } } }, "/api/mpp-info": { "get": { "operationId": "getMppInfo", "summary": "MPP payment rail discovery (Tempo chain, settlement token, test endpoint)", "responses": { "200": { "description": "Rail parameters" } } } }, "/api/x402-info": { "get": { "operationId": "getX402Info", "summary": "x402 payment rail discovery (Base USDC, pay-to wallet)", "responses": { "200": { "description": "Rail parameters" } } } } } }