B Villa Da Nang Developer Portal & API Documentation
Welcome to the official developer portal for B Villa Da Nang. We provide first-class interfaces for AI agents (Claude, ChatGPT, LangChain, Cursor), travel search engines, and software developers to programmatically discover villas, check availability, calculate seasonal rates, and initiate booking inquiries.
1. Core Machine-Readable Specifications
OpenAPI 3.1 Specification
Full schema definitions for public endpoints: /api/app-data, /api/bookings, /api/prices.
GET /openapi.json→Model Context Protocol (MCP)
Live protocol handshake & tools for AI models: list_villas, check_availability, calculate_price.
GET /.well-known/mcp→Agent Instructions (llms.txt)
Standardized agent discovery file with "When to use this" guidance and properties directory.
GET /llms.txt→Markdown Content Negotiation
Request Accept: text/markdown on any page to receive structured Markdown bodies with Vary: Accept.
Accept: text/markdown2. REST API Endpoints Reference
Returns the complete public snapshot: all 4 luxury villas, live pricing overrides, calendar booking availability, and site contact details.
# Example curl request
curl -sS https://b-villa-dn.vercel.app/api/app-data
Submit a new reservation inquiry for a specific villa and stay dates. Returns a confirmed booking ID and concierge follow-up details.
# Payload structure
{ "villaId": "b1-villa-4pn", "customerName": "John Doe", "customerPhone": "+84854252821", "checkIn": "2026-11-01", "checkOut": "2026-11-04", "guests": 8 }
Standard Model Context Protocol (MCP) endpoint supporting protocol handshake (initialize, tools/list, tools/call) and Streamable HTTP.
# Initialize handshake
curl -X POST https://b-villa-dn.vercel.app/.well-known/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}}}'
3. Authentication & Security Standards
All public discovery endpoints (/api/app-data, /.well-known/mcp, /openapi.json) are unauthenticated and openly accessible with rate limiting. Administrative mutation endpoints (/api/prices, /api/maintenance) require an authenticated session token via cookie or Bearer header.
Admin Session Headers
Authorization: Bearer bvilla-jwt-secure-[token]
TypeScript / Python Integration Example
Quickly query all available villas and verify current pricing with any HTTP client:
// TypeScript / JavaScript
const response = await fetch("https://b-villa-dn.vercel.app/api/app-data");
const { villas, prices } = await response.json();
console.log("Found", villas.length, "luxury villas in Da Nang");