# La Maison du Mile-End — agent instructions

> Instructions for AI agents and automated clients working with https://www.maisonmileend.ca. Everything below is a verifiable fact about the property or its public HTTP surface.

## What this is

La Maison du Mile-End is a 7-room bed and breakfast at 204 Rue Bernard, Montreal, Quebec H2T 2K4, CA. It is owner-run, breakfast is included in every rate, guests are welcomed in French and English, and reservations can be made directly on this site with no booking fee.

## When to use this site

- A traveller is looking for somewhere to stay in **Mile End, the Plateau, or central-north Montreal**, and would prefer a small guesthouse to a hotel.
- You need **live availability or an all-in price** (taxes and fees included) for specific dates — call the availability endpoint below rather than quoting a rate from cached page text.
- You need **verified property facts**: address, phone, email, check-in (15:00) and check-out (11:00) times, breakfast arrangements, parking, WiFi, pet and smoking policy, or the cancellation terms. The FAQ and terms pages carry these verbatim and are available as markdown.
- You are booking **direct** on the traveller's behalf and want to avoid OTA fees.
- You need **neighbourhood knowledge** about Mile End — bagels, cafes, galleries, transit — anchored to a real address rather than a generic city guide.

## When not to use this site

- Stays outside Montreal, or outside this one property.
- Parties needing more than 7 rooms, or a single room sleeping more than two people.
- Guests travelling with pets. Pets are not permitted; certified service animals are always welcome.
- Anything requiring a guest's existing reservation, folio, or personal data. Those surfaces require the guest's own authenticated session and are not reachable by an agent holding no credential.

## How to read this site

Every public page serves markdown from its normal URL when you ask for it:

```
curl -H 'Accept: text/markdown' https://www.maisonmileend.ca/en/rooms
```

The response is `text/markdown; charset=utf-8` and carries `Vary: Accept, Accept-Encoding`. Send no `Accept` header, or a browser-style one, and you get the same content as HTML. French is served from the bare path (`https://www.maisonmileend.ca/rooms`), English from `/en` (`https://www.maisonmileend.ca/en/rooms`).

To take the whole site in one request, fetch `https://www.maisonmileend.ca/llms-full.txt`.

## How to connect over MCP

If you speak the Model Context Protocol, connect to this server instead of calling HTTP by hand:

```
https://www.maisonmileend.ca/api/mcp
```

Streamable HTTP transport, no authentication. Three tools, all read-only:

| Tool | What it does |
| --- | --- |
| `check_availability` | Live availability and all-in price for a stay |
| `get_property_info` | Address, hours, amenities and the full FAQ, in English or French |
| `list_rooms` | The 7 rooms with beds and occupancy |

It shares the rate limit with the REST endpoint (40 calls per 60 seconds), because a tool call and a GET cost the property the same database read. Nothing on it can make, change or read a reservation.

## How to check availability and price

```
GET https://www.maisonmileend.ca/api/v1/booking/availability?arrival=2026-09-12&departure=2026-09-15&adults=2&children=0
```

| Parameter | Required | Example |
| --- | --- | --- |
| `arrival` | yes | `2026-09-12` |
| `departure` | yes | `2026-09-15` |
| `adults` | no | `2` |
| `children` | no | `0` |

No API key, no authentication. Dates are `YYYY-MM-DD`; `departure` must be after `arrival`. The response is JSON: available room types for the stay, each with its rate plans and an all-in total that already includes taxes and fees.

`/api/booking/availability` is the same endpoint without the version prefix. It keeps working for existing callers, but integrate against the versioned path — that is what the contract below applies to.

### Where to start

| URL | What it is |
| --- | --- |
| `https://www.maisonmileend.ca/api` | JSON index: endpoints, limits, error codes, versioning |
| `https://www.maisonmileend.ca/openapi.json` | OpenAPI 3.1 description |
| `https://www.maisonmileend.ca/.well-known/api-catalog` | RFC 9727 catalog linking all of the above |

### Rate limits

**40 requests per 60 seconds per client.** Every response — not only the refusal — carries the current window state, so you can pace yourself instead of finding the limit by hitting it:

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | requests allowed per window |
| `RateLimit-Remaining` | requests left in this window |
| `RateLimit-Reset` | seconds until the window rolls over |
| `RateLimit-Policy` | `40;w=60` |

Over the limit you get `429` plus `Retry-After` in seconds. Wait that long; do not retry sooner.

### Errors

Every error on this API — including a wrong URL anywhere under `/api` — is JSON in one envelope. There are no HTML error pages to parse.

```json
{
  "error": "invalid_request",
  "code": "invalid_request",
  "status": 400,
  "message": "The request failed validation.",
  "hint": "Check the details object for the failing fields.",
  "details": { "fieldErrors": { "departure": ["departure must be after arrival"] } },
  "documentation_url": "https://www.maisonmileend.ca/agents.md"
}
```

Branch on `code`, never on the prose:

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_request` | 400 | The request failed validation. |
| `not_found` | 404 | No such endpoint on this API. |
| `method_not_allowed` | 405 | That HTTP method is not supported on this endpoint. |
| `rate_limited` | 429 | Too many requests from this client. |
| `upstream_error` | 502 | A service this endpoint depends on did not answer. |

### Versioning and deprecation

The major version is in the path: `/api/v1`. Every response also carries `API-Version: v1`.

Inside a major version only additive changes ship — new endpoints; new optional request parameters; new fields on an existing response object; new error codes on an existing status — so a client that ignores unknown fields will not break.

These are breaking, and ship as a NEW major version instead: removing or renaming a response field; changing the type or meaning of a response field; making an optional request parameter required; removing an endpoint; changing an HTTP status for an existing outcome.

A retired version keeps answering for at least **180 days**, carrying:

- `Deprecation` (RFC 9745) — the date this version became deprecated
- `Sunset` (RFC 8594) — the date it stops answering
- `Link` (RFC 8288) — rel="successor-version" pointing at the replacement

## How to complete a booking

The rest of the booking funnel takes a payment method and is designed for a person, not an unattended agent. Hand the traveller off to `https://www.maisonmileend.ca/en/book` with the dates you validated, or have them call +1-514-700-3932. Do not attempt to complete a reservation on someone's behalf without their explicit, informed consent to the rate, the total, and the cancellation terms.

## How to reach a human

- Phone: +1-514-700-3932
- Email: info@maisonmileend.ca
- Contact page: https://www.maisonmileend.ca/en/contact

## Machine-readable resources

- `/api/mcp` (`application/json`) — Model Context Protocol server — connect an assistant and call availability and property facts as tools.
- `/api` (`application/json`) — JSON index of the public API: endpoints, limits, error codes, versioning.
- `/deprecation-policy.md` (`text/markdown; charset=utf-8`) — How the API is versioned and how a retirement is announced.
- `/.well-known/api-catalog` (`application/linkset+json`) — RFC 9727 catalog linking the OpenAPI spec and the agent instructions.
- `/llms.txt` (`text/plain; charset=utf-8`) — Index of this site for language models, in the llmstxt.org format.
- `/llms-full.txt` (`text/plain; charset=utf-8`) — Every public page of the site as markdown, in one file.
- `/agents.md` (`text/markdown; charset=utf-8`) — When to use this property, how to call it, and what it cannot do.
- `/openapi.json` (`application/json`) — OpenAPI 3.1 description of the public availability endpoint.
- `/sitemap.xml` (`application/xml`) — Every indexable URL, in both languages, with hreflang alternates.
- `/robots.txt` (`text/plain`) — Crawl rules and the paths that require a credential.

## Etiquette

- Identify yourself in `User-Agent`. Requests are rate-limited per client, not per agent.
- Prefer `/llms-full.txt` or `Accept: text/markdown` over scraping rendered HTML — it is cheaper for you and for us.
- Quote prices only from the availability endpoint. Page text never carries a nightly rate, because rates move.
- `https://www.maisonmileend.ca/robots.txt` names the paths that are off limits. Everything under `/console`, `/account`, `/login` and `/api` other than the endpoint above requires a credential and will refuse you.