Drive your property from your own code or AI assistant: a REST API with scoped keys, signed webhooks, and a tenant-scoped read-only MCP for safe hotel operations.
API keys
The Hotelumo REST API lets a channel manager, a booking engine, a CRM or your own back office do what the dashboard does: read and write reservations and guests, keep rooms and room types in sync, publish rate plans and per-day prices, and query availability.
Create an API key in the Hotelumo dashboard. The secret is shown once, when the key is created, and never again — store it somewhere safe. A key always belongs to one organization; it can additionally be pinned to a single hotel, in which case every request it makes is confined to that hotel and the hotel never has to be sent.
Authenticate every request with HTTP Basic auth carrying only the key secret, base64-encoded, in the Authorization header.
# The Authorization header is HTTP Basic auth carrying only the key secret,
# with no username and no colon.
Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)Every endpoint lives under https://api.hotelumo.com. Requests made with a key are rate limited per key; going over the limit returns 429.
Quick start
Read the reservations of a hotel, check what is still bookable over the next two weeks, then push prices back for a rate plan.
# List the reservations of one of your hotels
curl "https://api.hotelumo.com/api/reservations?hotelId=HOTEL_ID&limit=20" \
-H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)"
# Read the next two weeks of availability for that hotel
curl https://api.hotelumo.com/api/hotels/HOTEL_ID/availability \
-H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)"
# Push prices back: a batch upsert keyed on (ratePlanId, date).
# price is in minor units of the rate plan's currency, so 12000 is 120.00.
curl -X POST https://api.hotelumo.com/api/dailyRates \
-H "Authorization: Basic $(printf %s YOUR_API_KEY_SECRET | base64)" \
-H "Content-Type: application/json" \
-d '{
"values": [
{ "ratePlanId": "RATE_PLAN_ID", "date": "2026-08-01", "price": 12000 },
{ "ratePlanId": "RATE_PLAN_ID", "date": "2026-08-02", "price": 13500 }
]
}'Browse the full API reference — every endpoint with its parameters, request body, responses and required scope.
CLI
The same reservations, guests, rooms, rate plans and availability are available from your terminal through the hotelumo CLI. Install it globally with npm, or run it ad hoc with npx.
Authentication is one command: hotelumo login opens your browser to sign in to your Hotelumo account and stores a session for later commands — no API key to paste. For unattended use, export HOTELUMO_API_KEY instead and skip the login step entirely.
# Install once, globally
npm install -g hotelumo
# or run it ad hoc without installing
npx hotelumo --help
# Log in — opens your browser to sign in and stores a session
hotelumo login
# Who is arriving this month?
hotelumo reservations list --stayDateFrom 2026-08-01 --stayDateTo 2026-08-31
# What is still bookable for a two-night stay?
hotelumo availability check HOTEL_ID --checkInDate 2026-08-10 \
--checkOutDate 2026-08-12
# Publish prices for a date range. price is in minor units, so 12000 is 120.00
hotelumo daily-rates set --hotelId HOTEL_ID --ratePlanId RATE_PLAN_ID \
--dateFrom 2026-08-01 --dateTo 2026-08-31 --price 12000 --availability 4Every subcommand accepts --json for parseable output, and hotelumo schema prints the whole command tree as JSON, so a script never has to scrape help text.
The CLI is open source at github.com/hotelumo/cli and published as hotelumo on npm. Run any command with --help to see its options.
Scopes
Each key carries a list of scopes, so an integration that only needs to read your bookings never gets the ability to change your prices. New keys start read-only; widen them explicitly in the dashboard. A request whose key is missing the scope an endpoint requires is refused with 403.
A reservation or guest that belongs to another organization answers 404 rather than 403, so an id cannot be probed for existence.
AI assistants
Connect ChatGPT, Claude, Cursor or another MCP-compatible assistant to Hotelumo with one hosted endpoint. Sign in with Hotelumo OAuth; the connector is tenant-scoped, read-only and requires the hotelumo:read scope. There is no API secret to paste into the host.
{
"mcpServers": {
"hotelumo": {
"type": "http",
"url": "https://mcp.hotelumo.com/mcp"
}
}
}The public connector deliberately omits guest identities and contact details, individual reservation and room-allocation records, occupant identifiers, notes, documents, access codes, payment data, credentials, integration configuration and arbitrary metadata. Schedule results are aggregate counts only; the connector cannot create bookings, change rates, take payments or modify Hotelumo records.
Availability and catalog prices are returned in minor currency units: for example, 12000 is 120.00 when the hotel currency uses two decimal places. Bounded results that end in a plus sign are lower bounds, not complete totals.
Use the production MCP endpoint or connect through the Hotelumo listing in a supported AI host after its directory publication is live.
Agent Skills
Hotelumo ships Agent Skills — guides following the agentskills.io standard that teach coding agents how to run hotel operations with the hotelumo CLI and the MCP connector, instead of guessing at commands and tools.
# Install the Hotelumo skills into your coding agent
npx skills add hotelumo/skillsOne command installs the skills into Claude Code, Cursor, Codex, Gemini CLI and any other agent that follows the Skills standard. The CLI also bundles the same guides, version-matched to the commands it ships: hotelumo skills get <name> prints one on demand.
The two guides are not interchangeable. The CLI guide covers the full REST API, writes included; the hotel-operations guide covers the read-only MCP connector and its privacy boundary.
The skills are open source at github.com/hotelumo/skills. Claude users can also install the Hotelumo Claude plugin, which bundles the connector together with the skill: github.com/hotelumo/claude-plugin.
Webhooks
Add a webhook subscription to a hotel and Hotelumo POSTs the events you picked to your server as they happen. Every writer emits: the REST API, the dashboard, the public booking page and connected channel managers.
POST https://your-server.com/hotelumo-webhook
X-Hotelumo-Event: reservation.created
X-Hotelumo-Signature: t=1719000000,v1=<hmac-sha256 hex>
Content-Type: application/json
{
"event": "reservation.created",
"timestamp": 1719000000,
"data": { "...": "..." }
}Every delivery carries an X-Hotelumo-Signature header of the form t=timestamp,v1=signature, where the signature is an HMAC-SHA256 of timestamp.body keyed by the subscription secret shown to you once when the subscription was created. Recompute it over the raw body and compare before trusting the payload.
import crypto from 'node:crypto'
// body must be the RAW request body, byte for byte
function verify(header, body, secret) {
const [t, v1] = (header || '').split(',').map(part => part.split('=')[1])
if (!t || !v1) return false
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${body}`)
.digest('hex')
// timingSafeEqual throws on a length mismatch, so a malformed signature
// has to be rejected before the comparison rather than by it.
if (v1.length !== expected.length) return false
return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
}Delivery is one best-effort attempt with a five second timeout and no retries, so respond 2xx quickly and do the work asynchronously. An endpoint that fails twenty times in a row is disabled automatically and has to be re-enabled in the dashboard.
Start building