{ "openapi": "3.1.0", "info": { "title": "Avvican Vacation Rental API", "description": "Search vacation rentals, check availability, and book holiday homes in Gran Canaria, Spain. Avvican manages premium properties for travelers looking for authentic island experiences.", "version": "1.1.0", "contact": { "name": "Avvican", "url": "https://avvican.com", "email": "info@avvican.com" } }, "servers": [ { "url": "https://avvican.com" } ], "paths": { "/agent-api/properties": { "get": { "operationId": "listProperties", "summary": "List available vacation rentals", "description": "Returns all vacation rental properties in Gran Canaria with pricing, amenities, capacity and location data.", "parameters": [ { "name": "location", "in": "query", "description": "Filter by area/zone (e.g. 'Las Palmas', 'Maspalomas', 'Mogan', 'Agaete')", "schema": { "type": "string" } }, { "name": "guests", "in": "query", "description": "Minimum number of guests required", "schema": { "type": "integer" } }, { "name": "min_price", "in": "query", "description": "Minimum price per night in EUR", "schema": { "type": "integer" } }, { "name": "max_price", "in": "query", "description": "Maximum price per night in EUR", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of properties", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "location": { "type": "string" }, "city": { "type": "string" }, "guests": { "type": "integer" }, "bedrooms": { "type": "integer" }, "bathrooms": { "type": "integer" }, "pricePerNight": { "type": "number" }, "amenities": { "type": "array", "items": { "type": "string" } }, "coverImage": { "type": "string" }, "bookingUrl": { "type": "string" } } } } } } } } } } } }, "/agent-api/properties/{slug}": { "get": { "operationId": "getProperty", "summary": "Get detailed information about a specific property", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Property slug identifier (e.g. 'villa-mar', 'el-loft-de-clara')", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Property details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } } } } }, "404": { "description": "Property not found" } } } }, "/agent-api/check-availability": { "post": { "operationId": "checkAvailability", "summary": "Check if a property is available for specific dates", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["property_slug", "check_in", "check_out"], "properties": { "property_slug": { "type": "string", "description": "The slug identifier of the property (e.g. 'villa-mar')" }, "check_in": { "type": "string", "format": "date", "description": "Check-in date (YYYY-MM-DD)" }, "check_out": { "type": "string", "format": "date", "description": "Check-out date (YYYY-MM-DD)" }, "guests": { "type": "integer", "description": "Number of guests (default: 2)" } } } } } }, "responses": { "200": { "description": "Availability status and pricing", "content": { "application/json": { "schema": { "type": "object", "properties": { "available": { "type": "boolean" }, "property_slug": { "type": "string" }, "property_title": { "type": "string" }, "check_in": { "type": "string" }, "check_out": { "type": "string" }, "nights": { "type": "integer" }, "guests": { "type": "integer" }, "pricing": { "type": "object", "nullable": true, "properties": { "price_per_night": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" } } } } } } } } } } }, "/agent-api/create-booking": { "post": { "operationId": "createBooking", "summary": "Create a reservation hold and return the AvaiBook payment URL", "description": "Creates a PENDING_PAYMENT hold in AvaiBook. Payment and final confirmation are completed by the guest on AvaiBook's own checkout page (payment_url). This API never processes card data or confirms payment. Requires X-API-Key header — contact info@avvican.com.", "security": [{ "apiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["property_id", "check_in", "check_out", "guests", "guest_name", "guest_email"], "properties": { "property_id": { "type": "string", "description": "Property slug identifier" }, "check_in": { "type": "string", "format": "date" }, "check_out": { "type": "string", "format": "date" }, "guests": { "type": "integer" }, "guest_name": { "type": "string" }, "guest_email": { "type": "string", "format": "email" }, "guest_phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "Reservation hold created. Guest must complete payment at payment_url.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string", "enum": ["pending_payment"] }, "reservationId": { "type": "string" }, "payment_url": { "type": "string", "description": "AvaiBook checkout URL — send guest here to complete payment" }, "next_step": { "type": "string" } } } } } }, "401": { "description": "Missing or invalid API key" }, "409": { "description": "Property not available for requested dates" } } } }, "/agent-api/guarded-run": { "post": { "operationId": "guardedRun", "summary": "AI-orchestrated property search and booking with safety guardrails", "description": "Accepts a natural-language intent. Internally uses Gemini function calling to search properties, check availability, and optionally create a booking — all behind a guardrail layer that enforces a maximum of 3 tool calls and requires explicit confirmation before booking. Requires X-API-Key header.", "security": [{ "apiKey": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["intent"], "properties": { "intent": { "type": "string", "description": "Natural-language request, e.g. 'Find a 2-bedroom apartment in Las Palmas for 4 guests from Aug 1 to Aug 8'" }, "context": { "type": "array", "description": "Optional prior conversation turns", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": ["user", "assistant"] }, "content": { "type": "string" } } } }, "max_steps": { "type": "integer", "description": "Hard cap on tool calls (1–3, default 3)" }, "confirm_booking": { "type": "boolean", "description": "Set to true to confirm a pending booking returned in a previous requires_confirmation response" } } } } } }, "responses": { "200": { "description": "Orchestration result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["success", "requires_confirmation", "blocked"] }, "reasoning": { "type": "string" }, "tool_calls_used": { "type": "integer" }, "result": { "type": "object", "nullable": true } } } } } }, "401": { "description": "Missing or invalid API key" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } } } }