Rate Ranger Api

Rate Ranger watches what a hotel charges after your user has already booked it, and emails them if the rate drops far enough to be worth rebooking. Free, no account, no app.

This repository is the public contract for doing that programmatically: an OpenAPI spec, an MCP connector manifest, and worked examples.

• MCP connector: https://www.rateranger.io/api/mcp
• HTTP API: https://www.rateranger.io/api/agent/bookings
• Guide: https://www.rateranger.io/for-agents/
• OpenAPI 3.1: openapi.json

Do not drive the web form

The form at rateranger.io is protected by a CAPTCHA that issues no token to an automated browser. An assistant will fill every field correctly and then fail at the last step with nothing to click. Use the connector or the API instead.

Option 1: the MCP connector

Add https://www.rateranger.io/api/mcp as a custom connector. No key, no account, no setup beyond the URL.

It exposes two tools:

Tool	What it does
submit_hotel_booking	Enrols one to ten bookings for one traveller
check_hotel_booking	Reads a booking back, including whether it is confirmed yet

Works in ChatGPT (Developer Mode), Claude Code and Cursor. It does not work as a claude.ai custom connector, which requires OAuth; there is no way to declare a server unauthenticated there.

The server speaks protocol revisions 2026-07-28, 2025-11-25, 2025-06-18 and 2025-03-26, so both the current per-request-metadata shape and the older initialize handshake work.

Option 2: the HTTP API

curl -X POST https://www.rateranger.io/api/agent/bookings \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "agent": "my-assistant/1.0",
    "bookings": [{
      "hotel_name": "Novotel Bali Ubud Resort",
      "city": "Ubud",
      "country": "ID",
      "check_in_date": "2027-07-14",
      "check_out_date": "2027-07-17",
      "total_price": 742.50,
      "currency": "USD"
    }]
  }'

Answers 202 Accepted with a read_token per booking.

The traveller has to confirm. Tell them so.

A successful submission monitors nothing. Rate Ranger emails the traveller one link. Until they click it, no price is checked and no alert can fire. If they never click, everything is deleted after 7 days.

So do not tell your user their booking is being tracked. Tell them to check their inbox, then confirm it yourself with check_hotel_booking or GET /api/agent/bookings/{token} before you say anything stronger. Look at booking.confirmed, which is false until they act.

This is why no key is needed. The endpoint takes an email address from whoever calls it, so if submission alone started the service, anyone could sign any address up for mail it never asked for. The confirmation step is what makes an open API safe to leave open.

country is required, and it matters

ISO 3166-1 alpha-2, for example JP or ID. It decides which rate source can find the hotel at all. A booking without one cannot be monitored properly, so it is required here even though the web form treats it as optional.

Limits

	Per day
Anonymous caller, by IP	50 bookings
With a key	100 bookings
One email address, from one caller	3 bookings
One email address, from anyone	10 bookings

Email [email protected] for a key if you need more.

Prices may include decimals. Only the web form restricts them to whole numbers.

Errors

Every error carries a stable code to branch on, plus a message for a human reading a log. Branch on code; the wording may change.

Code	Meaning
invalid_email	Not a valid address
disposable_email	A throwaway provider, which cannot receive alerts
invalid_token	Signature failed, wrong token type, or expired
not_found	Token verified but matches no booking
rate_limited	A daily limit was reached

Full request and response shapes are in openapi.json.

Support

[email protected]