{
  "schemaVersion": "1.0",
  "apiVersion": "1.3",
  "name": "Hotel Bergsonne Allgäu Booking API",
  "mcpEndpoint": "https://bergsonne-allgaeu.de/api/booking-mcp",
  "mcpRegistry": "https://registry.modelcontextprotocol.io/v0/servers?search=de.bergsonne-allgaeu/booking",
  "mcpServerCard": "https://bergsonne-allgaeu.de/.well-known/mcp/server-card.json",
  "ard": "https://bergsonne-allgaeu.de/.well-known/ard.json",
  "openapi": "https://bergsonne-allgaeu.de/api/openapi",
  "description": "Machine-actionable booking API for AI agents. Search availability, get pricing, and create reservations. All query parameters are case-insensitive. roomId values are room type abbreviation codes (e.g. KAPDZ, KDZ, KFZ, SDZ) returned by the availability endpoint. Dates accept multiple formats: YYYY-MM-DD, DD.MM.YYYY, MM/DD/YYYY, or natural language like 'February 22, 2026'. All prices are in EUR, inclusive of VAT.",
  "baseUrl": "https://bergsonne-allgaeu.de/api/booking",
  "factSheet": "https://bergsonne-allgaeu.de/fact-sheet",
  "nlweb": "https://bergsonne-allgaeu.de/.well-known/nlweb.json",
  "_pricing": {
    "currency": "EUR",
    "taxIncluded": true,
    "note": "Published prices are per person per night in EUR, VAT included, breakfast included. City tax (Kurtaxe) of 3.50 EUR per person per night is already included and must not be added. Room totals returned by the API are labelled roomTotal and cover the whole room for the whole stay."
  },
  "actions": [
    {
      "name": "getHotelDetails",
      "mcpToolName": "get_hotel_details",
      "description": "Fetch hotel metadata, amenities, images, check-in/out times, and room types with abbreviation codes (roomId)",
      "method": "GET",
      "params": {
        "action": "hotel"
      },
      "exampleUrl": "https://bergsonne-allgaeu.de/api/booking?action=hotel",
      "inputSchema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "const": "hotel"
          }
        },
        "required": [
          "action"
        ]
      }
    },
    {
      "name": "searchAvailability",
      "mcpToolName": "search_availability",
      "description": "Search room availability and pricing for given dates and guests. Returns a roomTypes array with roomId codes (e.g. KAPDZ, KDZ, KFZ, SDZ) to use for getPriceQuote and createBooking. Dates accept YYYY-MM-DD, DD.MM.YYYY, MM/DD/YYYY, or natural language.",
      "method": "GET",
      "params": {
        "action": "availability",
        "checkIn": "YYYY-MM-DD (required)",
        "checkOut": "YYYY-MM-DD (required)",
        "adults": "number (required)",
        "children": "number (optional, default 0)"
      },
      "exampleUrl": "https://bergsonne-allgaeu.de/api/booking?action=availability&checkIn=2026-11-27&checkOut=2026-11-29&adults=2",
      "inputSchema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "const": "availability"
          },
          "checkIn": {
            "type": "string",
            "description": "Check-in date (YYYY-MM-DD)"
          },
          "checkOut": {
            "type": "string",
            "description": "Check-out date (YYYY-MM-DD)"
          },
          "adults": {
            "type": "integer",
            "minimum": 1
          },
          "children": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          }
        },
        "required": [
          "action",
          "checkIn",
          "checkOut",
          "adults"
        ]
      }
    },
    {
      "name": "getPriceQuote",
      "mcpToolName": "get_price_quote",
      "description": "Get a nightly price breakdown for a specific room type. roomId must be an abbreviation code from searchAvailability results (e.g. KAPDZ, KDZ, KFZ, SDZ).",
      "method": "GET",
      "params": {
        "action": "price-quote",
        "roomId": "string (required, abbreviation code e.g. KAPDZ)",
        "checkIn": "YYYY-MM-DD (required)",
        "checkOut": "YYYY-MM-DD (required)",
        "adults": "number (required)"
      },
      "exampleUrl": "https://bergsonne-allgaeu.de/api/booking?action=price-quote&roomId=KAPDZ&checkIn=2026-11-27&checkOut=2026-11-29&adults=2",
      "inputSchema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "const": "price-quote"
          },
          "roomId": {
            "type": "string",
            "enum": [
              "KAPDZ",
              "KDZ",
              "KFZ",
              "SDZ"
            ]
          },
          "checkIn": {
            "type": "string"
          },
          "checkOut": {
            "type": "string"
          },
          "adults": {
            "type": "integer",
            "minimum": 1
          }
        },
        "required": [
          "action",
          "roomId",
          "checkIn",
          "checkOut",
          "adults"
        ]
      }
    },
    {
      "name": "getFactSheet",
      "mcpToolName": "get_fact_sheet",
      "description": "Full GIATA property fact sheet with descriptions, amenities, images, and room classifications. German content only. Separate from hotel details (which returns operational WBE data).",
      "method": "GET",
      "params": {
        "action": "fact-sheet"
      },
      "exampleUrl": "https://bergsonne-allgaeu.de/api/booking?action=fact-sheet",
      "inputSchema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "const": "fact-sheet"
          }
        },
        "required": [
          "action"
        ]
      }
    },
    {
      "name": "createBooking",
      "mcpToolName": "create_booking",
      "description": "Create a reservation. Requires POST with JSON body. Mandatory customer fields: firstName, lastName, phone, email, country. Also requires roomId (abbreviation code), rateId, checkIn, checkOut, adults. Add test:true for sandbox mode (returns TEST bookingId, no real reservation). Add idempotencyKey to prevent duplicate bookings on retries.",
      "method": "POST",
      "params": {
        "action": "bookings"
      },
      "exampleUrl": "https://bergsonne-allgaeu.de/api/booking?action=bookings",
      "inputSchema": {
        "type": "object",
        "properties": {
          "roomId": {
            "type": "string",
            "enum": [
              "KAPDZ",
              "KDZ",
              "KFZ",
              "SDZ"
            ],
            "description": "Room type abbreviation code"
          },
          "rateId": {
            "type": "string"
          },
          "checkIn": {
            "type": "string",
            "description": "YYYY-MM-DD"
          },
          "checkOut": {
            "type": "string",
            "description": "YYYY-MM-DD"
          },
          "adults": {
            "type": "integer",
            "minimum": 1
          },
          "children": {
            "type": "integer",
            "minimum": 0,
            "default": 0
          },
          "customer": {
            "type": "object",
            "required": [
              "firstName",
              "lastName",
              "email",
              "phone",
              "country"
            ],
            "properties": {
              "firstName": {
                "type": "string"
              },
              "lastName": {
                "type": "string"
              },
              "email": {
                "type": "string",
                "format": "email"
              },
              "phone": {
                "type": "string",
                "description": "e.g. +49 170 1234567"
              },
              "country": {
                "type": "string",
                "description": "ISO code e.g. DE, AT, CH"
              },
              "salutation": {
                "type": "string"
              },
              "address": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "zip": {
                "type": "string"
              },
              "remarks": {
                "type": "string"
              }
            }
          },
          "test": {
            "type": "boolean",
            "default": false,
            "description": "Set true for sandbox mode"
          },
          "idempotencyKey": {
            "type": "string",
            "description": "Unique key to prevent duplicate bookings"
          }
        },
        "required": [
          "roomId",
          "rateId",
          "checkIn",
          "checkOut",
          "adults",
          "customer"
        ]
      },
      "exampleBody": {
        "roomId": "KAPDZ",
        "rateId": "DIREKTUEBERNACHTUNGS",
        "checkIn": "2026-11-27",
        "checkOut": "2026-11-29",
        "adults": 2,
        "customer": {
          "firstName": "Max",
          "lastName": "Mustermann",
          "email": "max@example.com",
          "phone": "+49 170 1234567",
          "country": "DE"
        },
        "test": true
      }
    },
    {
      "name": "chatbotApi",
      "description": "REST-only chatbot integration endpoint for third-party AI chatbots (e.g. Dialogflow, Botpress, custom). Supports get_hotel, search_availability, get_price_quote, create_booking via action parameter. Requires Bearer token authentication (CHATBOT_API_TOKEN). This is NOT an MCP tool — use the MCP endpoint for native MCP clients.",
      "method": "GET/POST",
      "baseUrl": "https://bergsonne-allgaeu.de/api/booking-chatbot-api",
      "authentication": "Bearer token (X-Chatbot-Token or Authorization header)",
      "params": {
        "action": "get_hotel | search_availability | get_price_quote | create_booking"
      },
      "exampleUrl": "https://bergsonne-allgaeu.de/api/booking-chatbot-api?action=get_hotel",
      "inputSchema": {
        "type": "object",
        "properties": {
          "action": {
            "type": "string",
            "enum": [
              "get_hotel",
              "search_availability",
              "get_price_quote",
              "create_booking"
            ]
          },
          "checkIn": {
            "type": "string",
            "description": "Arrival date (multiple formats accepted)"
          },
          "checkOut": {
            "type": "string",
            "description": "Departure date"
          },
          "adults": {
            "type": "string",
            "description": "Number of adults"
          },
          "children": {
            "type": "string",
            "description": "Number of children"
          },
          "roomId": {
            "type": "string",
            "enum": [
              "KAPDZ",
              "KDZ",
              "KFZ",
              "SDZ"
            ]
          },
          "rateId": {
            "type": "string"
          },
          "customer": {
            "type": "object",
            "description": "Customer details (POST body for create_booking)"
          }
        },
        "required": [
          "action"
        ]
      }
    }
  ],
  "developerPortal": "https://bergsonne-allgaeu.de/developers",
  "agentInstructions": "https://bergsonne-allgaeu.de/.well-known/agent-instructions.md",
  "whenToUse": "Availability, rates, room and property details, accessibility and care-room facts, opening hours, contact data and direct booking for Hotel Bergsonne Allgaeu in Sonthofen, Oberallgaeu, Germany.",
  "whenNotToUse": "Other hotels or multi-property search; cancellations or modifications of existing bookings; payments, invoices or guest records; bulk crawling without travel intent (rate limited, HTTP 429 RATE_LIMITED).",
  "errors": {
    "format": "JSON with error, code, hint, docs, openapi",
    "codes": {
      "INVALID_DATES": 400,
      "UNKNOWN_ACTION": 400,
      "FORBIDDEN_ORIGIN": 403,
      "NOT_FOUND": 404,
      "METHOD_NOT_ALLOWED": 405,
      "RATE_LIMITED": 429,
      "UPSTREAM_ERROR": 502
    }
  },
  "auth": {
    "readAccess": "open — no token required",
    "writeAccess": "OAuth 2.1 authorization code + PKCE (S256), scope booking:write",
    "scopes": {
      "hotel:read": "Read hotel metadata, room types, amenities, fact sheet and bookable extras.",
      "booking:read": "Read availability, rates and price quotes.",
      "booking:write": "Create a reservation on behalf of a named human guest."
    },
    "scopes_supported": [
      "hotel:read",
      "booking:read",
      "booking:write"
    ],
    "selfServeRegistration": "POST https://bergsonne-allgaeu.de/agent/auth",
    "protectedResourceMetadata": "https://bergsonne-allgaeu.de/.well-known/oauth-protected-resource",
    "authorizationServerMetadata": "https://bergsonne-allgaeu.de/.well-known/oauth-authorization-server",
    "documentation": "https://bergsonne-allgaeu.de/.well-known/auth.md"
  },
  "sandbox": {
    "supported": true,
    "mode": "server-url-or-request-flag",
      "baseUrl": "https://bergsonne-allgaeu.de/api/booking/sandbox",
    "flag": "test",
    "credentialsRequired": false,
    "description": "Call the sandbox base URL POST https://bergsonne-allgaeu.de/api/booking/sandbox?action=bookings (test mode forced server-side) or set \"test\": true in POST /api/booking?action=bookings. Identical validation and pricing, no real reservation, bookingId prefixed with TEST-.",
    "documentation": "https://bergsonne-allgaeu.de/developers"
  },
  "onboarding": {
    "readAccess": "open — no key, account or registration required",
    "selfServeCredential": "POST https://bergsonne-allgaeu.de/agent/auth — anonymous, instant, grants hotel:read and booking:read",
    "humanApprovalRequired": false,
    "contactSalesRequired": false,
    "sandbox": {
      "supported": true,
      "mode": "server-url-or-request-flag",
      "baseUrl": "https://bergsonne-allgaeu.de/api/booking/sandbox",
      "flag": "test",
      "credentialsRequired": false,
      "description": "Call the sandbox base URL POST https://bergsonne-allgaeu.de/api/booking/sandbox?action=bookings (test mode forced server-side) or set \"test\": true in POST /api/booking?action=bookings. Identical validation and pricing, no real reservation, bookingId prefixed with TEST-.",
      "documentation": "https://bergsonne-allgaeu.de/developers"
    }
  },
  "agentSkills": "https://bergsonne-allgaeu.de/.well-known/agent-skills/index.json"
}