docs · sandbox

Give your assistant bookable offers.

One API over MCP or REST. Search hotels and experiences, show your user an offer with its tracked link and disclosure, and follow your share of each confirmed booking.

Quickstart

Same key, same services. Base URL https://smesh.io.

MCP · Streamable HTTP · /mcp

{
  "mcpServers": {
    "smesh": {
      "type": "http",
      "url": "https://smesh.io/mcp",
      "headers": { "Authorization": "Bearer <test key>" }
    }
  }
}

REST · JSON · /v1

# every request
Authorization: Bearer <test key>

POST /v1/offers/search
GET  /v1/offers/:id
POST /v1/links
GET  /v1/conversions?status=…
GET  /v1/earnings

Five tools

Tool	What it does	REST
search_offers	Find bookable hotel stays or experiences. Ranked offers with a price, an estimated commission, a tracked book_url and a disclosure. One vertical per call.	POST /v1/offers/search
get_offer	The stored snapshot of an offer you were shown, with its current book_url.	GET /v1/offers/:id
create_tracked_link	A fresh tracked book_url for an offer you were shown, for example when the previous link expired.	POST /v1/links
get_conversions	Bookings attributed to your links, with status and your share.	GET /v1/conversions
get_earnings	Your share by currency: pending, approved, payable, reversed. Notional in the sandbox.	GET /v1/earnings

Request & response

Amounts are in minor units. The response is abbreviated to one offer.

POST /v1/offers/search
{
  "vertical": "experience",
  "destination": "Amsterdam",
  "date_from": "2026-11-14",
  "date_to": "2026-11-14",
  "party": { "adults": 2 },
  "end_user_ref": "u_7f3a"   // optional, opaque id only
}

200 OK
{
  "query_id": "q_…",
  "sandbox": true,
  "offers": [
    {
      "offer_id": "off_…",
      "title": "Sample experience",
      "price": { "amount_minor": 12800, "currency": "EUR", "indicative": true },
      "commission": { "rate_bps": 800, "est_commission_minor": 1024, "est_agent_share_minor": 614 },
      "book_url": "https://smesh.io/c/…",
      "disclosure": {
        "is_affiliate_link": true,
        "commission_influences_ranking": false,
        "ranking_parameters": ["rating", "price"],
        "text": "Affiliate link: the router and your AI agent may earn a commission if you book. …"
      }
    }
  ]
}

Show the link. Never follow it.

+ must

Show book_url exactly as given
Show disclosure.text with it, unedited
Leave the click to the person

− never

Open or fetch book_url
Prefetch or unfurl it
Shorten, wrap or rewrite it

Automated hits are filtered before any redirect and never earn commission.

Earnings

Each conversion moves through these states in an append-only ledger.

pending ──supplier confirms──▶ approved ──14-day holdback + partner paid──▶ payable
   │                              │
   └──────── cancelled ───────────┴──────────────────────────────────▶ reversed

pending: Booked through your link. Your share is an estimate.
approved: The supplier confirmed it after the stay or tour.
payable: After the 14-day holdback, once the partner has paid us.
reversed: Cancelled or not confirmed: the commission is clawed back.

No personal data

Send only the documented fields. Names, email addresses or phone numbers are rejected with pii_rejected; unknown fields with invalid_request. To tell your users apart, pass an opaque end_user_ref.

Test keys on request

Sandbox data only. Earnings are notional.

Request a test key