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 7 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.

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": "2026-05-01",
  "check_out": "2026-05-04",
  "guests": 2
}

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

// Tool: get_hotel_details
{
  "hotel_id": "htl_x9y8z7"
}

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

// Tool: book_hotel
{
  "hotel_id": "htl_x9y8z7",
  "rate_code": "RAC-STK-F8E2",
  "check_in": "2026-05-01",
  "check_out": "2026-05-04",
  "guests": 2,
  "guest_name": "Jane Smith",
  "guest_email": "jane@example.com"
}

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

API Keys &
Auth

All requests require a Bearer token in the Authorization header. API keys are issued per application and scoped to either sandbox or production mode.

Authorization: Bearer 1stay_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sandbox keys begin with sk_test_. Production keys begin with 1stay_live_. You'll receive your key after approval and Stripe onboarding.

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 available hotels by location and dates. Returns a ranked list of properties with rates and a search_id valid for 15 minutes. The canonical entry point for any booking flow.

{
  "location": "Nashville, TN",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "guests": 1
}

{
  "search_id": "srch_a1b2c3d4e5f6",
  "expires_at": "2026-06-12T14:45:00Z",
  "count": 34,
  "hotels": [
    {
      "hotel_id": "htl_x9y8z7w6",
      "name": "The Hermitage Hotel",
      "address": "231 6th Ave N, Nashville, TN",
      "stars": 5,
      "from_rate": 189.00,
      "currency": "USD",
      "loyalty_eligible": true,
      "distance_miles": 0.25
    }
    // ... more hotels
  ]
}

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

Create a reservation using a rate_code from get_hotel_details. Returns a secure checkout URL where the guest completes payment. The reservation is not confirmed until the guest pays.

{
  "hotel_id": "htl_x9y8z7w6",
  "rate_code": "RAC-STK-F8E2",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "guests": 2,
  "guest_name": "Jane Smith",
  "guest_email": "jane@example.com"
}

{
  "checkout_url": "https://booking.stayker.com/hotel?hotel_id=htl_x9y8z7w6&check_in=2026-06-12&check_out=2026-06-15",
  "hotel": "The Hermitage Hotel",
  "check_in": "2026-06-12",
  "check_out": "2026-06-15",
  "total": 567.00,
  "currency": "USD",
  "status": "pending_payment",
  "expires_at": "2026-06-12T15:15:00Z"
}

get_booking

Retrieve the details of an existing booking by booking_id. Scoped to your API key — you can only retrieve bookings created with your key.

{
  "booking_id": "bk_9f8e7d6c",
  "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"
}

retrieve_booking

Find a reservation and resend the confirmation email. This is the guest-facing lookup tool — it requires identity verification before any information is accessed. Confirmation is sent to the email on file (not returned in the response) to protect guest privacy.

{
  "status": "found",
  "message": "Found your reservation. A confirmation email has been resent to the email address on file."
}

cancel_booking

Cancel an existing reservation. Requires identity verification — the guest's name and confirmation number must match. Cancellation is subject to the hotel's cancellation policy. Always surface the policy to the guest before confirming cancellation.

{
  "booking_id": "stk_bk_9f8e7d6c",
  "status": "cancelled",
  "cancellation_number": "CXL-4421",
  "penalty": 0,
  "refund_amount": 567.00,
  "cancelled_at": "2026-06-11T09:14:22Z"
}

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 7 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_...) return realistic test data without making real reservations. Use sandbox for development, integration testing, and demos.

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

Questions? Email hello@1stay.ai.