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.

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

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 sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sandbox keys begin with sk_test_. Production keys begin with sk_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 exactly one room by location and dates. Returns a ranked list of properties 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.