# smesh 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.

## Connect

MCP (Streamable HTTP):

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

REST: base URL `https://smesh.io/v1`. Send `Authorization: Bearer <test key>` with every request. Optional: `Smesh-Version: 2026-10-08`.

Test keys are free. Get one at https://smesh.io/keys.html: confirm your email address and we email the key.

## 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 `book_url` and `disclosure.text` exactly as returned, and make clear it's an affiliate link.
- Never open, prefetch, preview, shorten, rewrite or cloak a link. Never click your own links.
- Never send names, email addresses, phone numbers or payment details. Use `end_user_ref` with an ID that means nothing outside your system.
- Don't call an offer the best or the lowest price, and don't suggest a supplier endorses you.
- 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.

## Contact

hello@smesh.io · [Developer docs](https://smesh.io/developers.html) · [Developer terms](https://smesh.io/terms.html)