1Stay API
Reference

1Stay gives AI agents and applications access to real hotel inventory — 300,000+ properties across 140+ countries — through a simple MCP server. Reservations use the hotel's own confirmation number. Loyalty points are eligible. You're never the merchant of record.

The MCP server name is 1stay at endpoint mcp.stayker.com. There are 8 tools covering the complete booking lifecycle.

MCP Server Details

// Claude Desktop / claude_desktop_config.json
{
  "mcpServers": {
    "1stay": {
      "url": "https://mcp.stayker.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Authorization: Bearer YOUR_API_KEY

What Makes This Different

Most hotel APIs are OTA-style: you buy inventory, mark it up, you're the merchant. 1Stay is infrastructure: your agent connects guests to hotels directly. The hotel charges the guest. You build the experience, your users pay for your product — 1Stay is the booking layer that makes it possible. No inventory risk, no float, no chargebacks.

Muse
Integration

1Stay for Muse runs on its own endpoint and supports the full booking lifecycle with the same 8 tools as every other 1Stay connection. What differs is how bookings and cancellations are completed: in Muse, the guest approves the final booking, and any cancellation, in the conversation. The general developer flow in the rest of these docs is unchanged.

Muse Endpoint

• Connector name: 1Stay
• Muse MCP endpoint: https://mcp.stayker.com/mcp/muse
• Authentication: none. The Muse endpoint accepts connections without an API key and does not use OAuth.
• This endpoint is separate from the general developer endpoint at https://mcp.stayker.com/mcp.

Tools in Muse

• search_hotels — search by location and dates, one room per search in the first release
• get_hotel_details — room types, live rates, cancellation policies, amenities
• book_hotel — prepare, check, and confirm a booking, as described below
• get_booking / lookup_booking — find and retrieve a reservation. Verification always requires the guest's full name, plus either the hotel confirmation number or the booking email together with the last four digits of the card
• resend_confirmation — resend the confirmation to the email on file
• cancel_booking — prepare, check, and confirm a cancellation, as described below
• search_tools — discover tools at runtime

Booking in Muse

The approval summary shows:

• The hotel (the seller), with 1Stay by Stayker as the service provider
• Room type, rate plan, dates, guest count, and one room
• Room subtotal, taxes, any hotel fees, and the total, in the stated currency
• The 1Stay service fee, shown as its own line when the booking has one (some bookings have no service fee)
• The rate's cancellation policy and guarantee or deposit policy
• When each charge happens, and that there are no recurring charges

Who Charges What

• The stay: the hotel is the merchant of record and charges the room rate, taxes, and any hotel fees directly, under the rate's guarantee or deposit and cancellation policy.
• The 1Stay service fee: some bookings have no service fee. When there is one, it is charged by Stayker and processed through Stripe, as a separate charge. It is authorized before booking and charged only after the hotel confirms the reservation. It is non-refundable once the booking is confirmed, except where required by law.

The approval summary shows the stay and any service fee as separate lines, and together they match what the guest is charged.

Price Changes and Failures

• If the rate, taxes, fees, or policy change before confirmation, 1Stay does not book at the new price. It returns the change and requires a new review and approval.
• If the approved details change in any way, the quote hash no longer matches and the booking is refused until the user approves again.
• 1Stay never creates a duplicate booking or charge. A FAILED or EXPIRED attempt needs a new quote and fresh approval.

Cancellation in Muse

The cancellation summary shows:

• The hotel, the hotel confirmation number, dates, and room
• The cancellation policy and any cancellation deadline recorded with the reservation
• The guarantee policy and any financial terms on file
• The email address that will receive the cancellation confirmation

• 1Stay does not estimate a refund, credit, penalty, or hotel charge. Cancellation terms are set by the hotel.
• 1Stay returns CANCELLED only when the hotel's system confirms the reservation is cancelled. If the reservation is already cancelled, the tool says so instead of cancelling again.
• If the summary changes or expires before confirmation, the cancellation is refused until the user reviews and approves a new summary.

Status and Support

After booking, Muse can check booking status, resend confirmations, and cancel using the hotel confirmation number and the verification above. Guests can get help at stayker.com/service or service@stayker.com. Data handling for Muse is covered in the Muse addendum to the MCP Data Processing Terms.

Quick
Start

From zero to a hotel checkout link in three tool calls. The canonical flow for any AI agent.

// Tool: search_hotels
{
  "location": "Austin, TX",
  "check_in": "2027-01-15",
  "check_out": "2027-01-18",
  "guests_per_room": 2
}

// Returns: list of hotels with hotel_id, rates, rate_code per rate

// Tool: get_hotel_details
{
  "hotel_id": "htl_x9y8z7",
  "check_in": "2027-01-15",
  "check_out": "2027-01-18",
  "guests": 2
}

// Returns: rates[], room types, cancellation policies, amenities

// Tool: book_hotel
{
  "hotel_id": "htl_x9y8z7",
  "rate_code": "RAC-STK-F8E2",
  "check_in": "2027-01-15",
  "check_out": "2027-01-18",
  "guests": 2
}

// Returns: checkout_url, total — guest pays at checkout URL

API Keys &
Auth

The MCP endpoint accepts connections without a key and does not use OAuth. For developer-scoped access and attribution, send your API key as a Bearer token in the Authorization header. API keys are issued per application and scoped to either sandbox or production mode.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sandbox keys begin with sk_test_. Production keys begin with sk_live_. When you apply, we email you a one-time link to reveal your sandbox key.

Key Scopes

Production plans include 50,000 searches per month with overage billed at $0.002/search. Sandbox keys use test properties and never charge guests. Production keys access live inventory and create real reservations.

search_hotels

Search for exactly one room by location and dates. Returns a representative selection of properties across brands (not a ranking) with rates and a search_id valid for 15 minutes. The first 1Stay release supports one room per search and reservation.

{
  "location": "Nashville, TN",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "guests_per_room": 2
}

{
  "search_id": "srch_a1b2c3d4e5f6",
  "total_results": 4,
  "cursor": "next-page-token",
  "has_more": true,
  "results": [
    {
      "hotel_id": "htl_x9y8z7w6",
      "name": "The Hermitage Hotel",
      "star_rating": 5,
      "total_stay": 654.37,
      "avg_nightly_rate": 189.00,
      "booking_fee": 7.00,
      "currency": "USD",
      "reward_points_eligible": true
    }
  ]
}

get_hotel_details

Get room types, live rates, amenities, and cancellation policies for a specific hotel. This is the tool your agent calls before booking — it returns rate_code values needed by book_hotel. Rate codes expire in ~15 minutes.

{
  "hotel_id": "TP-MC-DALCC",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "guests": 2
}

{
  "hotel": {
    "hotel_id": "TP-MC-DALCC",
    "name": "Dallas Marriott City Center",
    "chain": "Marriott",
    "check_in_time": "15:00",
    "check_out_time": "12:00"
  },
  "rooms": [
    {
      "room_id": "rm_01",
      "name": "King Guest Room",
      "description": "One king bed, city view",
      "bed_type": "King",
      "max_occupancy": 2,
      "rate_plans": [
        {
          "rate_code": "RAC-STK-A1B2",
          "name": "Best Available Rate",
          "avg_nightly_rate": 189.00,
          "subtotal": 572.00,
          "taxes": 82.37,
          "total_with_taxes": 654.37,
          "currency": "USD",
          "nightly_breakdown": [
            { "date": "2026-06-12", "amount": 189.00 },
            { "date": "2026-06-13", "amount": 189.00 },
            { "date": "2026-06-14", "amount": 189.00 }
          ],
          "refundable": true,
          "cancellation_policy": "Free cancellation until 48hrs before arrival",
          "reward_points_eligible": true,
          "booking_type": "Direct hotel confirmation"
        }
      ]
    }
  ],
  "rate_quote_expires_at": "2026-06-10T14:45:00Z",
  "rate_quote_ttl_seconds": 900
}

book_hotel

Start secure checkout for exactly one room using a rate_code from get_hotel_details. The tool accepts no guest identity or payment fields. A reservation is created only after the guest completes checkout.

{
  "hotel_id": "htl_x9y8z7w6",
  "rate_code": "RAC-STK-F8E2",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "guests": 2
}

{
  "status": "ACTION_REQUIRED",
  "message": "Complete the reservation on the secure checkout page.",
  "checkout_url": "https://book.1stay.ai/checkout/…",
  "total_with_taxes": 567.00,
  "booking_fee": 7.00,
  "currency": "USD",
  "expires_in_minutes": 15
}

get_booking

Retrieve an existing reservation exclusively by the hotel's confirmation number. Anonymous callers also pass the booking-scoped verification token returned by lookup_booking. Internal Stayker booking IDs are never accepted or disclosed through MCP.

{
  "status": "confirmed",
  "confirmation_number": "HLC-98234",
  "hotel": "The Hermitage Hotel",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "guest_name": "Jane Smith",
  "total": 567.00,
  "created_at": "2026-06-10T14:52:33Z"
}

lookup_booking

Look up a reservation with identity verification. The guest must provide their name plus at least one verification factor. Returns a booking summary with status, dates, and hotel information.

{
  "status": "confirmed",
  "confirmation_number": "HLC-98234",
  "hotel": "The Hermitage Hotel",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "guest_name": "Jane Smith"
}

resend_confirmation

Resend a confirmation using either the hotel confirmation number, or blind full-name + email recovery when the guest does not know it. Recovery never reveals whether a reservation matched and sends only to the email already on file. The email contains the hotel confirmation number needed for lookup or cancellation.

{
  "status": "sent",
  "message": "Confirmation email has been resent to the email address on file."
}

cancel_booking

Create a secure cancellation handoff. The guest's name and hotel confirmation number must match. The tool returns the hotel's cancellation policy and a first-party 1Stay URL; it never cancels the reservation in the conversation.

{
  "status": "ACTION_REQUIRED",
  "message": "Review and confirm on the secure cancellation page.",
  "confirmation_number": "HLC-98234",
  "cancellation_url": "https://book.1stay.ai/cancel/…",
  "cancellation_url_expires_at": "2026-06-11T09:24:22Z",
  "cancellation": { "policy_summary": "Hotel policy on file" }
}

search_tools

Discover available MCP tools and their capabilities at runtime. Useful for agents that want to dynamically understand what operations are supported without relying on static documentation.

{
  "server": "1stay",
  "version": "1.0.0",
  "tools": [
    {
      "name": "search_hotels",
      "description": "Search available hotels by location and dates",
      "parameters": { /* schema */ }
    }
    // ... all 8 tools
  ]
}

Error
Codes

All errors return a JSON body with an error field (machine-readable code) and a message field (human-readable). Design your agent to handle these gracefully.

Rate Change
Handling

Hotel rates are live inventory. Any price difference between when you called get_hotel_details and when you call book_hotel may trigger a 409 rate_changed response — even a difference of $0.01. No exceptions. No silent overrides. The guest always sees every change.

{
  "error": "rate_changed",
  "original_rate": { "nightly": 189.00, "total": 567.00 },
  "new_rate": { "nightly": 209.00, "total": 627.00 },
  "difference": { "nightly": 20.00, "total": 60.00, "direction": "increase" }
}

If you receive a rate_changed response, surface the new rate to the guest and let them decide. To proceed at the new rate, start a fresh book_hotel call. If the guest declines, call search_hotels again to find alternatives.

What your agent should say

Access
Tiers

API capabilities and limits vary by access tier. All tiers use the same endpoints, response formats, and error codes — only the data volume and booking behavior differ.

Sandbox
Mode

Sandbox keys (sk_test_...) run against a test inventory rather than the production catalogue, and make no real reservations. The API surface is identical — same tools, same response shapes, same error codes — but it holds fewer properties and does not cover every destination. Most major cities populate; secondary markets and smaller towns may return nothing at all. An empty sandbox search is expected behaviour rather than an integration fault, and production coverage is not limited this way — if a search comes back empty, retry a major metro before debugging the call. Use sandbox for development and integration testing. Do not demo on it, and do not judge catalogue coverage from it.

Switch from sandbox to production by swapping your key from sk_test_ to sk_live_. No other code changes required.

Questions? Email hello@1stay.ai.