Agent quickstart
smesh gives your agent bookable hotels and experiences. Each offer comes with a tracked link and a disclosure that your user sees. When your user books through the link, the agent's developer can earn a share of the commission.
Test keys work today. Your agent gets real booking links as each supplier goes live. This page is also available as Markdown to paste into a system prompt.
Connect
MCP clients that support Streamable HTTP connect to /mcp. Everything else calls the REST API at https://smesh.io/v1. Send your test key with every request. Test keys are free: get one here, confirm your email address, and we email the key.
{ "mcpServers": { "smesh": { "url": "https://smesh.io/mcp",
"headers": { "Authorization": "Bearer <test key>" } } } }
# REST: send with every request; Smesh-Version is optional
Authorization: Bearer <test key>
Smesh-Version: 2026-10-08
The five tools
| Tool | REST | When to call it | Required input | Returns |
|---|---|---|---|---|
| search_offers | POST /v1/offers/search | Your user wants a hotel or something to do | vertical ("hotel" or "experience"), destination, date_from, date_to (YYYY-MM-DD), party.adults | Ranked offers with price, estimated commission, book_url and disclosure |
| get_offer | GET /v1/offers/{offer_id} | You need an offer again | offer_id | The offer as we sent it, with its current book_url |
| create_tracked_link | POST /v1/links | A link has expired (links last up to 7 days) | offer_id | A fresh book_url |
| get_conversions | GET /v1/conversions | The developer wants to see bookings | optional status | Bookings made through your links, with status and share |
| get_earnings | GET /v1/earnings | The developer wants totals | none | Share per currency, by status |
Search one category per call. search_offers allows 60 calls a minute per test key, and all tools together allow 120 calls a minute.
How to show an offer
For each offer, show your user the title, the price, the book_url and the disclosure.text, exactly as smesh returned them. For example:
Canal cruise, 75 min: €24.00 per person https://smesh.io/c/… Affiliate link. smesh and this assistant may earn a commission if you book. Prices are set by the supplier and may differ on the supplier's site. Commission doesn't affect the ranking.
Don't open, fetch, preview or shorten the link. Your user clicks it and books and pays on the supplier's site.
Must and never
- show
- Show book_url and disclosure.text exactly as returned, and make clear it's an affiliate link.
- never open
- Never open, prefetch, preview, shorten, rewrite or cloak a link. Never click your own links.
- no personal data
- Never send names, email addresses, phone numbers or payment details. Use end_user_ref with an ID that means nothing outside your system.
- honest claims
- Don't call an offer the best or the lowest price, and don't suggest a supplier endorses you.
- no incentives
- No cashback, rewards or other incentives for clicks or bookings.
Errors and what to do
| HTTP | Code | What to do |
|---|---|---|
| 400 | invalid_request | Send only the documented fields |
| 400 | pii_rejected | Remove the personal data and retry |
| 400 | invalid_json | Fix the request body |
| 400 | invalid_api_version | Use a listed Smesh-Version, or leave the header out |
| 401 | unauthorized | Check your test key and the Authorization header |
| 404 | not_found | Check the path or the offer_id |
| 409 | partner_unavailable | Search again |
| 429 | rate_limited | Wait the seconds in the Retry-After header, then retry |
| 500 | internal | Retry later |
Over MCP, errors come back as tool results with isError: true and the same code in the text.
System prompt snippet
When the user asks for hotels or things to do on a trip, call search_offers. Show each offer's title, price, book_url and disclosure.text exactly as returned. Never open or fetch a book_url. Never send the user's name, email address or phone number to smesh. Don't describe an offer as the best or the cheapest.
Questions
Email [email protected], or read the developer docs and the developer terms.