{ "openapi": "3.1.0", "info": { "title": "AmsterdamBB API", "version": "1.0.0", "summary": "Read-only facts, availability, prices, FAQ and events for the Boatsuite on houseboat Kadans, Amsterdam.", "description": "Public, read-only JSON API of AmsterdamBB (one private suite for up to 2 guests on a houseboat on KNSM Island, Amsterdam). No authentication. CORS is open for GET. Rate limit: 60 requests per minute per IP. Nothing here books or charges: to book, send the guest to the bookingUrl; the guest pays on amsterdambb.com. Also available as an MCP server at https://amsterdambb.com/mcp.", "contact": { "name": "AmsterdamBB", "email": "hello@amsterdambb.com", "url": "https://amsterdambb.com" } }, "servers": [ { "url": "https://amsterdambb.com" } ], "externalDocs": { "description": "llms.txt with page links and agent instructions", "url": "https://amsterdambb.com/llms.txt" }, "paths": { "/api/v1/property": { "get": { "operationId": "getProperty", "summary": "Facts, policies, amenities, address, check-in/out times and photos", "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "nl", "de", "es", "fr", "it" ], "default": "en" }, "description": "Language of texts and URLs." } ], "responses": { "200": { "description": "Property facts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Property" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (60 requests per minute per IP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/availability": { "get": { "operationId": "getAvailability", "summary": "Available nights, minimum stay and nightly prices (max 120 days per request)", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "First night (default today)." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "description": "Last night (default from + 60 days)." } ], "responses": { "200": { "description": "Nightly availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (60 requests per minute per IP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Live data (Lodgify) unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/quote": { "get": { "operationId": "getQuote", "summary": "Exact all-in price for a stay, with deposit now and balance date", "parameters": [ { "name": "arrival", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "departure", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "guests", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 2, "default": 2 } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "nl", "de", "es", "fr", "it" ], "default": "en" }, "description": "Language of texts and URLs." } ], "responses": { "200": { "description": "All-in quote", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (60 requests per minute per IP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Live data (Lodgify) unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/faq": { "get": { "operationId": "searchFaq", "summary": "Questions and answers matching a query, with the URL of the page that answers them", "parameters": [ { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "nl", "de", "es", "fr", "it" ], "default": "en" }, "description": "Language of texts and URLs." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search words; empty returns all." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } ], "responses": { "200": { "description": "Matching Q&A", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqResults" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (60 requests per minute per IP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/events": { "get": { "operationId": "listEvents", "summary": "Upcoming concerts and city events with venue, page and travel time from the boat", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "lang", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "en", "nl", "de", "es", "fr", "it" ], "default": "en" }, "description": "Language of texts and URLs." } ], "responses": { "200": { "description": "Upcoming events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Events" } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited (60 requests per minute per IP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "required": [ "error", "message", "status" ], "properties": { "error": { "type": "string", "examples": [ "invalid_dates", "rate_limited", "unavailable" ] }, "message": { "type": "string" }, "status": { "type": "integer" } } }, "Property": { "type": "object", "required": [ "name", "description", "url", "address", "suite", "stay", "policies", "photos", "updated" ], "properties": { "name": { "type": "string" }, "alternateName": { "type": "string" }, "subtitle": { "type": "string" }, "language": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "type": { "type": "string" }, "boat": { "type": "object" }, "hosts": { "type": "array", "items": { "type": "string" } }, "address": { "type": "object", "required": [ "street", "postalCode", "city", "country", "lat", "lng" ], "properties": { "street": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "district": { "type": "string" }, "island": { "type": "string" }, "area": { "type": "string" }, "country": { "type": "string" }, "countryName": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "mapsUrl": { "type": "string", "format": "uri" } } }, "suite": { "type": "object", "required": [ "name", "maxGuests", "bedroomM2", "bathroomM2", "amenities" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "maxGuests": { "type": "integer", "maximum": 2 }, "bedrooms": { "type": "integer" }, "bed": { "type": "string" }, "bedNote": { "type": [ "string", "null" ] }, "bedroomM2": { "type": "number" }, "bathroomM2": { "type": "number" }, "shower": { "type": "string" }, "bathtub": { "type": "boolean" }, "privateDeck": { "type": "boolean" }, "ownEntrance": { "type": "boolean" }, "amenities": { "type": "array", "items": { "type": "string" } } } }, "stay": { "type": "object", "required": [ "checkIn", "checkOut", "minNightsUsual" ], "properties": { "checkIn": { "type": "string", "examples": [ "15:00" ] }, "checkOut": { "type": "string", "examples": [ "11:00" ] }, "selfCheckIn": { "type": "boolean" }, "minNightsUsual": { "type": "integer" }, "minNightsGapOrQuiet": { "type": "integer" }, "breakfast": { "type": "boolean" }, "smoking": { "type": "boolean" }, "pets": { "type": [ "boolean", "null" ] } } }, "policies": { "type": "object" }, "ratings": { "type": "object" }, "contact": { "type": "object" }, "registration": { "type": "string" }, "languagesSpoken": { "type": "array", "items": { "type": "string" } }, "photos": { "type": "array", "items": { "type": "object", "required": [ "url", "alt" ], "properties": { "url": { "type": "string", "format": "uri" }, "alt": { "type": "string" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] } } } }, "links": { "type": "object", "additionalProperties": { "type": "string" } }, "updated": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } }, "Availability": { "type": "object", "required": [ "from", "to", "currency", "minStayUsual", "nights", "availableNights" ], "properties": { "from": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "truncated": { "type": "boolean", "description": "True when the range was cut to 120 days." }, "currency": { "type": "string", "examples": [ "EUR" ] }, "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "minStayUsual": { "type": "integer" }, "note": { "type": "string" }, "availableNights": { "type": "integer" }, "lowestNightlyPrice": { "type": [ "number", "null" ] }, "nights": { "type": "array", "items": { "type": "object", "required": [ "date", "available", "price", "minStay" ], "properties": { "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "available": { "type": "boolean" }, "price": { "type": [ "number", "null" ], "description": "Nightly room price, null when not available." }, "minStay": { "type": "integer", "description": "Minimum nights for an arrival on this date." } } } }, "bookingUrl": { "type": "string", "format": "uri" } } }, "Quote": { "type": "object", "required": [ "arrival", "departure", "nights", "guests", "currency", "total", "lines", "payNow", "balance" ], "properties": { "arrival": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "departure": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "nights": { "type": "integer" }, "guests": { "type": "integer", "minimum": 1, "maximum": 2 }, "available": { "type": [ "boolean", "null" ], "description": "Whether all nights are free right now (null if unknown)." }, "currency": { "type": "string" }, "total": { "type": "number", "description": "All-in price: room, cleaning, VAT and tourist tax." }, "lines": { "type": "array", "items": { "type": "object", "required": [ "label", "amount" ], "properties": { "label": { "type": "string" }, "amount": { "type": "number" } } } }, "taxesAndFeesIncluded": { "type": "boolean" }, "payNow": { "type": "number", "description": "Deposit charged when the guest books." }, "balance": { "type": "number" }, "balanceDue": { "type": [ "string", "null" ], "format": "date" }, "cancellation": { "type": "object" }, "bookingUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Prefilled booking page for the guest to open and pay." }, "note": { "type": "string" } } }, "FaqResults": { "type": "object", "required": [ "language", "query", "total", "results" ], "properties": { "language": { "type": "string" }, "query": { "type": "string" }, "total": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "question", "answer", "url" ], "properties": { "question": { "type": "string" }, "answer": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "page": { "type": "string" } } } }, "faqPage": { "type": "string", "format": "uri" } } }, "Events": { "type": "object", "required": [ "from", "to", "total", "events" ], "properties": { "from": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "total": { "type": "integer" }, "updated": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "events": { "type": "array", "items": { "type": "object", "required": [ "date", "name", "status" ], "properties": { "date": { "type": "string", "format": "date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": [ "string", "null" ], "format": "date" }, "startTime": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "tour": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "kind": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "planned", "sold-out", "postponed", "cancelled" ] }, "venue": { "type": [ "object", "null" ] }, "page": { "type": [ "string", "null" ], "format": "uri" }, "travelFromBoat": { "type": [ "object", "null" ], "properties": { "publicTransportThere": { "type": [ "integer", "null" ] }, "publicTransportBack": { "type": [ "integer", "null" ] }, "bike": { "type": [ "integer", "null" ] }, "car": { "type": [ "integer", "null" ] }, "route": { "type": [ "string", "null" ] }, "unit": { "type": "string" } } }, "sourceUrl": { "type": [ "string", "null" ], "format": "uri" } } } }, "eventsPage": { "type": "string", "format": "uri" }, "disclaimer": { "type": "string" } } } } } }