StayStaff AI API

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.

Base URL
http://localhost:3000

# Running locally:
http://localhost:3000

Authentication

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.
Which hotel is this key?
curl http://localhost:3000/api/me \
  -H "x-api-key: YOUR_API_KEY"

{
  "ok": true,
  "hotel": {
    "id": "azure-bay",
    "name": "Azure Bay Hotel & Spa"
  }
}
Your saved records (newest first)
curl "http://localhost:3000/api/records?kind=complaint&limit=50" \
  -H "x-api-key: YOUR_API_KEY"

# kind (optional): reservation, booking_link, change_request,
#   message, guest_request, complaint, group_lead
# limit (optional): 1-1000, default 200

Errors & limits

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"
  ]
}
StatusMeaning
200Done (ok: true) or can't be done (ok: false + error)
401Missing or wrong x-api-key, or unknown hotel
404Unknown tool, task or action
429Too 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.

  1. Add two settings to your website: STAYSTAFF_URL and STAYSTAFF_API_KEY.
  2. Add one server route that forwards allowed actions (below).
  3. Call /api/guest/availability, /api/guest/chat and the rest from your pages.
  4. Set HOTEL_SITE_URL in StayStaff so booking links Sofia sends by phone open your site's booking page (/book/confirm).
app/api/guest/[action]/route.ts (Next.js)
// Forward allowed guest actions to StayStaff AI. Your API key stays on the server.
const STAYSTAFF = process.env.STAYSTAFF_URL;      // e.g. https://ai-staffs.synthtrix.com
const KEY = process.env.STAYSTAFF_API_KEY;

const ACTIONS: Record<string, string> = {
  availability: "/api/tools/check_room_availability",
  reserve:      "/api/public/reserve",
  lookup:       "/api/tools/lookup_reservation",
  change:       "/api/tools/request_booking_change",
  request:      "/api/tools/log_guest_request",
  complaint:    "/api/tools/log_complaint",
  message:      "/api/tools/take_message",
  chat:         "/api/public/chat",
};

export async function POST(req: Request, ctx: { params: Promise<{ action: string }> }) {
  const { action } = await ctx.params;
  const path = ACTIONS[action];
  if (!path) return Response.json({ ok: false, error: "Not found." }, { status: 404 });

  const res = await fetch(STAYSTAFF + path, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-api-key": KEY! },
    body: JSON.stringify(await req.json()),
  });
  return Response.json(await res.json());
}
In the browser
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
DHandled 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.

FieldTypeDescription
check_in*stringCheck-in date, YYYY-MM-DD
check_out*stringCheck-out date, YYYY-MM-DD
adults*integerNumber of adults, at least 1
childrenintegerNumber of children, 0 if none
Request
curl -X POST http://localhost:3000/api/tools/check_room_availability \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"check_in":"2026-12-24","check_out":"2026-12-26","adults":2,"children":0}'
POST/api/tools/lookup_reservationAPI key
LHandled by Leah, Guest Services Agent

Look up an existing booking. Needs the guest's last name plus the booking reference or the check-in date.

FieldTypeDescription
last_name*stringGuest's last name
referencestringBooking reference, e.g. ABH-1002
check_instringCheck-in date YYYY-MM-DD, if no reference
Request
curl -X POST http://localhost:3000/api/tools/lookup_reservation \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"reference":"ABH-1002","last_name":"Lee"}'
POST/api/tools/request_booking_changeAPI key
DHandled by Daniel, Reservations Agent

Cancel a booking or change its dates. For modify, include the new dates. Read any fee to the guest and get a clear yes before confirming.

FieldTypeDescription
last_name*stringGuest's last name
referencestringBooking reference
check_instringOriginal check-in date YYYY-MM-DD, if no reference
change_type*"modify" | "cancel"modify or cancel
new_check_instringNew check-in YYYY-MM-DD (modify only)
new_check_outstringNew check-out YYYY-MM-DD (modify only)
Request
curl -X POST http://localhost:3000/api/tools/request_booking_change \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"reference":"ABH-1002","last_name":"Lee","change_type":"modify","new_check_in":"2026-12-08","new_check_out":"2026-12-10"}'
POST/api/tools/take_messageAPI key
SHandled by Sofia, Front Desk Receptionist

Take a message for a department when the caller can't be transferred or the AI can't answer.

FieldTypeDescription
department*"front_desk" | "reservations" | "housekeeping" | "restaurant" | "spa" | "events" | "management"
caller_name*stringCaller's name
callback_numberstringNumber to call back
message*stringThe message, in a short sentence or two
urgentbooleantrue if the caller says it's urgent
Request
curl -X POST http://localhost:3000/api/tools/take_message \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"department":"events","caller_name":"Ana Cruz","callback_number":"+1 555 0100","message":"Quote for a 40-guest wedding in June."}'
POST/api/tools/log_guest_requestAPI key
LHandled by Leah, Guest Services Agent

Send an in-house guest's request to the right team (towels, housekeeping, maintenance, room service, wake-up call, late checkout).

FieldTypeDescription
room_number*stringGuest's room number
request_type*"towels_amenities" | "housekeeping" | "maintenance" | "room_service" | "wake_up_call" | "late_checkout" | "other"
detailsstringDetails, e.g. 2 extra towels, wake-up at 6:30 AM
Request
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
JHandled 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.

FieldTypeDescription
room_numberstringRoom number if known
description*stringThe 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
CHandled by Camila, Guest Experience Advisor

Get add-ons and packages that fit this guest, to suggest one after they choose a room.

FieldTypeDescription
occasion"anniversary" | "honeymoon" | "birthday"
guest_type"leisure" | "business" | "couple" | "family"
childrenintegerNumber of children
Request
curl -X POST http://localhost:3000/api/tools/get_offers \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"occasion":"anniversary","guest_type":"couple"}'
POST/api/tools/qualify_group_leadAPI key
NHandled by Nadia, Groups & Events Sales

Score a group, wedding or event inquiry (5+ rooms) and get the next step to tell the caller.

FieldTypeDescription
contact_namestring
contact_phonestring
event_type*"wedding" | "corporate" | "conference" | "retreat" | "reunion" | "sports" | "family" | "other"
event_datestringYYYY-MM-DD if known
rooms_needed*integer
budget_per_roomnumberBudget per room per night in USD, if known
decision_makerbooleantrue if the caller makes the final decision
Request
curl -X POST http://localhost:3000/api/tools/qualify_group_lead \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"event_type":"wedding","event_date":"2027-06-12","rooms_needed":20,"budget_per_room":150,"decision_maker":true}'
POST/api/tools/get_dashboard_statsAPI key
EHandled by Elliot, Executive Assistant to the GM

Today's numbers for the manager: occupancy, arrivals, AI calls and bookings, open requests, reviews, leads and six months of revenue.

Request
curl -X POST http://localhost:3000/api/tools/get_dashboard_stats \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{}'
POST/api/tools/generate_invoiceAPI key
HHandled by Hana, Billing & Accounts

Create an invoice for a booking, with optional extras, tax and payment status.

FieldTypeDescription
reference*stringBooking reference
last_name*stringGuest's last name
extras{ offer_id, qty }[]Extras to add: breakfast, late-checkout, romance, airport, spa, family-fun, business
Request
curl -X POST http://localhost:3000/api/tools/generate_invoice \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"reference":"ABH-1003","last_name":"Tanaka","extras":[{"offer_id":"breakfast","qty":8}]}'
POST/api/tools/inventory_statusAPI key
MHandled by Mateo, Inventory & Purchasing

Stock levels, days left and suggested order quantities, with alerts for items to reorder now.

Request
curl -X POST http://localhost:3000/api/tools/inventory_status \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{}'
POST/api/tools/personalize_websiteAPI key
KHandled by Kai, Digital Experience Manager

Headline, featured room and offers to show a website visitor of a given type.

FieldTypeDescription
segment*"family" | "business" | "couple" | "budget" | "returning"Visitor type
Request
curl -X POST http://localhost:3000/api/tools/personalize_website \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"segment":"family"}'

Website endpoints

POST /api/public/{action}. No API key. Built to be called from your hotel website and the StayStaff sales site.

POST/api/public/availabilityNo key
DHandled by Daniel, Reservations Agent

Room search for a hotel website. Same input and output as check_room_availability.

FieldTypeDescription
check_in*stringCheck-in date, YYYY-MM-DD
check_out*stringCheck-out date, YYYY-MM-DD
adults*integerNumber of adults, at least 1
childrenintegerNumber of children, 0 if none
Request
curl -X POST http://localhost:3000/api/public/availability \
  -H "Content-Type: application/json" \
  -d '{"check_in":"2026-12-24","check_out":"2026-12-26","adults":2,"children":0}'
POST/api/public/reserveNo key
DHandled by Daniel, Reservations Agent

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.

FieldTypeDescription
room_type_id*stringRoom chosen from availability
check_in*stringYYYY-MM-DD
check_out*stringYYYY-MM-DD
adults*integerNumber of adults
childrenintegerNumber of children
name*stringGuest's full name
email*stringGuest's email
phonestringGuest's phone
requestsstringSpecial requests
refstringReference from a booking link Sofia sent (ABH-XXXXXX), kept as the confirmation number
Request
curl -X POST http://localhost:3000/api/public/reserve \
  -H "Content-Type: application/json" \
  -d '{"room_type_id":"deluxe-king","check_in":"2026-12-08","check_out":"2026-12-10","adults":2,"name":"Maria Santos","email":"maria@example.com"}'
POST/api/public/chatNo key
SHandled by Sofia, Front Desk Receptionist

Website chat with Sofia. Send the whole conversation each time; the reply is in `text`.

Uses the AI model; replies can take a few seconds. Limit: 15 per minute per visitor.

FieldTypeDescription
messages*{ role: "user" | "assistant", content: string }[]Conversation so far, last message from the user (max 20 kept)
Request
curl -X POST http://localhost:3000/api/public/chat \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Do you allow dogs?"}]}'
POST/api/public/personalizeNo key
KHandled by Kai, Digital Experience Manager

Personalized hero for a website visitor. Same as personalize_website.

FieldTypeDescription
segment*"family" | "business" | "couple" | "budget" | "returning"Visitor type
Request
curl -X POST http://localhost:3000/api/public/personalize \
  -H "Content-Type: application/json" \
  -d '{"segment":"family"}'
POST/api/public/leadNo key

A hotel asks to hire StayStaff (sales website form). Sends a "New hotel lead" event to your webhook.

Limit: 5 per minute per visitor.

FieldTypeDescription
hotel*stringHotel name
email*stringWork email
roomsstringNumber of rooms / interest
phonestringPhone
Request
curl -X POST http://localhost:3000/api/public/lead \
  -H "Content-Type: application/json" \
  -d '{"hotel":"Sunset Inn","email":"gm@sunsetinn.example","rooms":"24"}'

AI tasks

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"
}
taskStaffWhat it doesinput
receptionist_chatSSofiaChat reply as Sofiamessages: { role, content }[]
sales_objectionMMarcusWhat to say to a price objectionobjection
booking_reminderDDanielPre-arrival SMS or emailreference, channel: "sms" | "email"
marketingPPriyaPosts, ads, emails, OTA copy (2 versions)topic, content_type?, platform?, tone?
manager_briefEElliotDaily brief for the general managerfocus?
follow_upTTheoFollow-up message to a lead or guestcontext, name?, channel?, days?
review_replyGGraceSentiment, topics and a public replyreview, rating?, source?
complaint_analysisJJonahPatterns and fixes across complaintscomplaints (one per line)
data_analystRRajAnswers about monthly performancequestion
documentOOliverSummary, key terms and risks of a documenttext, doc_type?
recruitmentAAmaraScore and interview questions for an applicantapplication, job?
translateLLucíaTranslation and a suggested replytext, 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).

POST to your webhook
{
  "type": "New reservation",
  "at": "2026-11-16T09:42:11.000Z",
  "confirmation": "ABH-7C21F0",
  "name": "Maria Santos",
  "email": "maria@example.com",
  "phone": "+1 555 0101",
  "room": "Deluxe King",
  "check_in": "2026-12-08",
  "check_out": "2026-12-10",
  "adults": 2,
  "children": 0,
  "total": "$240",
  "requests": ""
}

Phone (Retell)

Sofia answers your phone through Retell. Each staff tool above is added in Retell as a Custom Function:

  1. URL: http://localhost:3000/api/tools/{tool}, method POST.
  2. Header: x-api-key: YOUR_API_KEY (your hotel's key, so calls and bookings are saved for your hotel).
  3. Name, description and parameters: exactly as listed in Staff tools (also in retell/functions.json).
  4. Add Retell's built-in Transfer Call with your front desk number, and paste retell/agent-prompt.md as the agent prompt.