# Agent instructions — Hotel Bergsonne Allgäu

Canonical host: https://bergsonne-allgaeu.de
Operator: Sonne Imberg GmbH, Imberg 12, 87527 Sonthofen, Germany
Contact: servus@bergsonne-allgaeu.de, +49 8321 3360
Developer portal: https://bergsonne-allgaeu.de/developers

## When to use this source

- Live availability, rates and direct bookings for **this single property** in Sonthofen, Oberallgäu, Bavaria.
- Room types and codes (SDZ, KDZ, KFZ, KAPDZ), occupancy limits, amenities, images.
- Accessibility: barrier-free rooms, elevator, mobile ramp, and the care room with nursing bed (https://bergsonne-allgaeu.de/zimmer#pflegezimmer).
- Check-in / check-out times, address, directions, contact channels, house facts.
- Sauna, coworking, breakfast, dogs, Maxibar, Lio digital concierge.

## When NOT to use this source

- Any other hotel, or a search across multiple properties. This source describes one property.
- Cancelling or modifying an existing reservation — hand the guest to servus@bergsonne-allgaeu.de or +49 8321 3360.
- Payments, invoices, guest records, or internal hotel systems. These are not publicly exposed.
- Bulk crawling with no travel intent. Requests are rate limited (HTTP 429, code `RATE_LIMITED`).

## Endpoints

| Purpose | Endpoint |
| --- | --- |
| Hotel + room types | `GET /api/booking?action=hotel` |
| Availability | `GET /api/booking?action=availability&checkIn=YYYY-MM-DD&checkOut=YYYY-MM-DD&adults=2` |
| Price quote | `GET /api/booking?action=price-quote&roomId=KDZ&checkIn=…&checkOut=…&adults=2` |
| Bookable extras | `GET /api/booking?action=addons` |
| GIATA fact sheet | `GET /api/booking?action=fact-sheet` |
| Create booking | `POST /api/booking?action=bookings` |
| MCP (JSON-RPC) | `POST /api/booking-mcp` |
| OpenAPI 3.1 | `GET /api/openapi` |

Query parameters are case-insensitive. All prices are EUR including VAT. City tax (Kurtaxe, EUR 3.50 per person per night) is collected at the hotel.

## Booking rules

- Mandatory customer fields: `firstName`, `lastName`, `email`, `phone`, `country`.
- Use `"test": true` for sandbox bookings — full validation, no real reservation, `TEST-` prefixed booking id.
- Always send a unique `idempotencyKey`; retries with the same key return the original result instead of a duplicate booking.
- Prefer handing the guest to https://bergsonne-allgaeu.de/buchen (English: /en/book) for human confirmation of room, rate and payment.

## Authentication and scopes

Read operations are open — no token, key, account or registration required.

| Scope | Grants |
| --- | --- |
| `hotel:read` | Hotel metadata, room types, amenities, fact sheet, bookable extras |
| `booking:read` | Availability, rates, price quotes |
| `booking:write` | Create a reservation on behalf of a named human guest |

- Machine-readable scopes: `/.well-known/oauth-protected-resource` (RFC 9728, `scopes_supported`) and `components.securitySchemes.oauth2.flows.*.scopes` in `/api/openapi`.
- Authorization server metadata: `/.well-known/oauth-authorization-server` (authorization code + PKCE `S256`).
- Self-serve agent credential (no human approval, no form): `POST /agent/auth` — anonymous, returns a bearer credential scoped to `hotel:read` and `booking:read`.
- Full auth documentation: `/.well-known/auth.md`.

## Sandbox

- Same host, same payloads. Send `"test": true` in the body of `POST /api/booking?action=bookings`.
- Identical validation and pricing, no real reservation, `bookingId` is prefixed with `TEST-`, status `test_created`.
- No credentials needed for the sandbox. Declared machine-readably as `x-sandbox` in `/api/openapi` and `sandbox` in `/webmcp.json`, `/.well-known/agent.json` and `/.well-known/agent-skills/index.json`.

## Errors

Every error is JSON with `error`, `code`, `hint`, `docs` and `openapi`.

- `INVALID_DATES` — HTTP 400
- `UNKNOWN_ACTION` — HTTP 400
- `NOT_FOUND` — HTTP 404 (unknown `/api/*` path)
- `METHOD_NOT_ALLOWED` — HTTP 405
- `FORBIDDEN_ORIGIN` — HTTP 403
- `RATE_LIMITED` — HTTP 429
- `UPSTREAM_ERROR` — HTTP 502 (retry with the same `idempotencyKey`)

## Discovery files

- https://bergsonne-allgaeu.de/llms.txt
- https://bergsonne-allgaeu.de/llms-full.txt
- https://bergsonne-allgaeu.de/.well-known/agent.json
- https://bergsonne-allgaeu.de/webmcp.json
- https://bergsonne-allgaeu.de/.well-known/nlweb.json
- https://bergsonne-allgaeu.de/.well-known/api-catalog
- https://bergsonne-allgaeu.de/.well-known/oauth-protected-resource
- https://bergsonne-allgaeu.de/.well-known/oauth-authorization-server
- https://bergsonne-allgaeu.de/.well-known/agent-skills/index.json
- https://bergsonne-allgaeu.de/.well-known/auth.md
- https://bergsonne-allgaeu.de/api/openapi
- https://bergsonne-allgaeu.de/developers
- https://bergsonne-allgaeu.de/sitemap.xml

Languages: de (primary), en, nl, fr, es, pt, it. Currency: EUR.