Connect your hotel website, phone line and systems to your AI staff. Every endpoint is a simple POST with a JSON body and returns JSON. Your website can search rooms with Daniel, take bookings, chat with Sofia, and send requests to Leah, all with a few lines of code.
Staff tools and AI tasks need your hotel's API key in the x-api-key header. Keep it on your server and never put it in browser code.
Header
x-api-key: YOUR_API_KEY
Staff tools (/api/tools/*) and AI tasks (/api/ai): API key required.
Website endpoints (/api/public/*): no key needed. Safe to call from a browser, and rate-limited per visitor. Send your x-api-key when calling from your server, or name your hotel with an x-hotel-id header from a browser.
Records (GET /api/records) and who am I (GET /api/me): API key required.
Every hotel gets its own API key and dashboard password. The key decides which hotel a call belongs to: everything it saves is tagged with your hotel, and you can only read or look up your own hotel's bookings and records.
Every response has ok. When a request is understood but can't be done (sold out, wrong last name, missing field), you get HTTP 200 with ok: false and a plain-language error that you can show to the guest or that an AI agent can read out.
Example: can't be done
{
"ok": false,
"error": "That room type is not available for those dates. Offer one of the available options instead.",
"available": [
"Standard Queen",
"Family Suite"
]
}
Status
Meaning
200
Done (ok: true) or can't be done (ok: false + error)
401
Missing or wrong x-api-key, or unknown hotel
404
Unknown tool, task or action
429
Too many requests from one visitor; wait a minute
Dates are always YYYY-MM-DD. Prices are in USD. Booking references look like ABH-1002.
Connect your hotel website
The simplest setup: your website's server forwards a short list of guest actions to StayStaff with your API key. Guests' browsers only ever talk to your own site.
Add two settings to your website: STAYSTAFF_URL and STAYSTAFF_API_KEY.
Add one server route that forwards allowed actions (below).
Call /api/guest/availability, /api/guest/chat and the rest from your pages.
Set HOTEL_SITE_URL in StayStaff so booking links Sofia sends by phone open your site's booking page (/book/confirm).
const res = await fetch("/api/guest/availability", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ check_in: "2026-12-24", check_out: "2026-12-26", adults: 2 }),
});
const data = await res.json();
if (data.ok) showRooms(data.available); // [{ room_type, total_price, rooms_left, ... }]
else showMessage(data.error); // e.g. "Check-out must be after check-in."
A complete example is the Azure Bay Hotel & Spa website, which uses exactly this setup.
Staff tools
POST /api/tools/{tool}. These are the same tools your AI staff use on phone calls. The body can be the arguments directly, or Retell's format { name, args, call }.
POST/api/tools/check_room_availabilityAPI key
Handled by Daniel, Reservations Agent
Check which rooms are available and their prices for the guest's dates and number of guests. Call whenever a guest asks about availability, rooms or prices for specific dates.
curl -X POST http://localhost:3000/api/tools/log_guest_request \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"room_number":"501","request_type":"towels_amenities","details":"2 extra bath towels"}'
POST/api/tools/log_complaintAPI key
Handled by Jonah, Guest Relations Manager
Log a guest complaint. Returns the category, severity, whether it was escalated to the duty manager, and what to tell the guest.
Field
Type
Description
room_number
string
Room number if known
description*
string
The complaint in the guest's words
Request
curl -X POST http://localhost:3000/api/tools/log_complaint \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"room_number":"308","description":"The AC is very loud at night."}'
POST/api/tools/get_offersAPI key
Handled by Camila, Guest Experience Advisor
Get add-ons and packages that fit this guest, to suggest one after they choose a room.
A guest completes a booking on the hotel website. Re-checks availability, confirms the reservation and sends a "New reservation" event to your webhook.
Limit: 5 per minute per visitor.
Field
Type
Description
room_type_id*
string
Room chosen from availability
check_in*
string
YYYY-MM-DD
check_out*
string
YYYY-MM-DD
adults*
integer
Number of adults
children
integer
Number of children
name*
string
Guest's full name
email*
string
Guest's email
phone
string
Guest's phone
requests
string
Special requests
ref
string
Reference from a booking link Sofia sent (ABH-XXXXXX), kept as the confirmation number
POST /api/ai with { task, input }. Your staff write or analyse something and return it as text. Replies can take a few seconds.
Request
curl -X POST http://localhost:3000/api/ai \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"task":"review_reply","input":{"source":"Google","rating":2,"review":"Room was nice but the AC was loud."}}'
Response
{
"ok": true,
"text": "SENTIMENT: mixed\nTOPICS: maintenance, room\nREPLY: Thank you for staying with us…",
"model": "your-model-id"
}
task
Staff
What it does
input
receptionist_chat
Sofia
Chat reply as Sofia
messages: { role, content }[]
sales_objection
Marcus
What to say to a price objection
objection
booking_reminder
Daniel
Pre-arrival SMS or email
reference, channel: "sms" | "email"
marketing
Priya
Posts, ads, emails, OTA copy (2 versions)
topic, content_type?, platform?, tone?
manager_brief
Elliot
Daily brief for the general manager
focus?
follow_up
Theo
Follow-up message to a lead or guest
context, name?, channel?, days?
review_reply
Grace
Sentiment, topics and a public reply
review, rating?, source?
complaint_analysis
Jonah
Patterns and fixes across complaints
complaints (one per line)
data_analyst
Raj
Answers about monthly performance
question
document
Oliver
Summary, key terms and risks of a document
text, doc_type?
recruitment
Amara
Score and interview questions for an applicant
application, job?
translate
Lucía
Translation and a suggested reply
text, target_language?
Webhooks
Set NOTIFY_WEBHOOK_URL and StayStaff sends a JSON event there for every new reservation and every new hotel lead. Works with Zapier, Make, a Google Sheet script, or a Slack incoming webhook (Slack gets a formatted message).
{
"ok": true,
"reference": "ABH-47361B",
"guest_name": "Maria Santos",
"room_type": "Deluxe King",
"check_in": "2026-12-08",
"check_out": "2026-12-10",
"nights": 2,
"total_price": 240,
"currency": "USD",
"booking_link": "http://localhost:3001/book/confirm?ref=ABH-47361B&room=deluxe-king&in=2026-12-08&out=2026-12-10&adults=2&children=0",
"message": "Booking link prepared for Maria Santos, reference ABH-47361B. Total $240. The room is confirmed once payment is completed on the secure link."
}
{
"ok": true,
"change_type": "modify",
"reference": "ABH-1002",
"old_dates": "2026-12-05 to 2026-12-08",
"new_dates": "2026-12-08 to 2026-12-10",
"old_total": 570,
"new_total": 360,
"difference": -210,
"message": "Family Suite is available for the new dates. New total $360. Change request MOD-299822 sent; the guest will get an updated confirmation by email."
}
Response
{
"ok": true,
"ticket": "MSG-486501",
"department": "Events & Groups",
"caller_name": "Ana Cruz",
"callback_number": "+1 555 0100",
"urgent": false,
"message": "Message passed to Events & Groups. They usually call back within 1 business day."
}
{
"ok": true,
"ticket": "CMP-43504B",
"room_number": "308",
"category": "maintenance",
"severity": "medium",
"escalated_to_manager": false,
"suggested_resolution": "Dispatch maintenance within 30 minutes; offer a room move if it cannot be fixed tonight; 10% off the night.",
"message": "Apologize sincerely. The team has been notified: Dispatch maintenance within 30 minutes; offer a room move if it cannot be fixed tonight; 10% off the night."
}
Response
{
"ok": true,
"recommended": [
{
"id": "romance",
"name": "Romance package",
"price": "$79 per stay",
"pitch": "Sparkling wine, rose petals, chocolates and late checkout."
},
{
"id": "spa",
"name": "Spa: 60-min massage",
"price": "$85 (15% off when booked with the room)",
"pitch": "Relaxing full-body massage at our in-house spa."
},
{
"id": "breakfast",
"name": "Breakfast buffet",
"price": "$18 per person per night",
"pitch": "Full buffet with made-to-order eggs, 6:30–10:30 AM."
}
],
"tip": "Offer at most 2, tied to what the guest told you. Accept a no gracefully."
}
Response
{
"ok": true,
"lead_id": "LEAD-B26618",
"contact_name": null,
"score": 100,
"rating": "hot",
"reasons": [
"Event type \"wedding\": +25",
"20 rooms: +25",
"Budget $150/room/night: +20",
"208 days away: +15",
"Speaking to the decision maker: +15"
],
"next_step": "Events manager calls back within 2 hours with a proposal and holds the rooms."
}
{
"ok": true,
"segment": "family",
"detected_from": "Searched 2 adults + 2 children, viewed pool page",
"hero_headline": "Family fun, made easy",
"hero_subtext": "Two-bedroom suites, a kids' pool and free breakfast for little ones.",
"featured_room": "Family Suite",
"featured_offers": [
"Family fun pack ($45 per stay)",
"Breakfast buffet ($18 per person per night)"
],
"call_to_action": "See family suites"
}
{
"ok": true,
"text": "Yes! Dogs under 15 kg are welcome for $25 per night. Would you like me to note that for your booking?",
"model": "your-model-id"
}
Response
{
"ok": true,
"segment": "family",
"detected_from": "Searched 2 adults + 2 children, viewed pool page",
"hero_headline": "Family fun, made easy",
"hero_subtext": "Two-bedroom suites, a kids' pool and free breakfast for little ones.",
"featured_room": "Family Suite",
"featured_offers": [
"Family fun pack ($45 per stay)",
"Breakfast buffet ($18 per person per night)"
],
"call_to_action": "See family suites"
}