{
  "openapi": "3.1.0",
  "info": {
    "title": "AITravel.az Agent API",
    "version": "1.0.0",
    "summary": "Public agent-ready API for AI assistants to plan trips and explore travel options in Azerbaijan and regional destinations.",
    "description": "AITravel.az is an AI-agent-ready travel platform. This API lets AI agents (ChatGPT, Claude, Gemini, Grok and others) search destinations, tours and excursions, generate itinerary drafts, estimate budgets and create travel request drafts. IMPORTANT: all prices are approximate; no booking is made automatically; every confirmed offer or booking requires an AITravel.az operator. Agents must not claim prices are final, must not modify prices, and must not delete or expose private user data.",
    "contact": { "name": "AITravel.az", "url": "https://aitravel.az/agents" },
    "license": { "name": "Proprietary" }
  },
  "servers": [
    { "url": "https://zdzwsxpbnebhbclomdcy.supabase.co/functions/v1/agent", "description": "Live agent API (Supabase Edge Function, public, CORS-enabled)" },
    { "url": "https://aitravel.az/api/agent", "description": "Planned vanity URL via reverse proxy (NOT live yet — use the live server above)" }
  ],
  "tags": [
    { "name": "discovery", "description": "Read-only travel data" },
    { "name": "planning", "description": "Itinerary and budget generation" },
    { "name": "leads", "description": "Travel request drafts (no booking)" }
  ],
  "paths": {
    "/plan-trip": {
      "post": {
        "tags": ["planning"],
        "operationId": "planTrip",
        "summary": "Generate a trip itinerary draft from a natural-language request.",
        "description": "Returns a structured day-by-day itinerary with approximate budget. Prices are estimates only.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/PlanTripRequest" },
              "example": { "query": "3-day budget trip to Baku for 2 people", "lang": "en", "travelers": "2" }
            }
          }
        },
        "responses": {
          "200": { "description": "Itinerary draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TripPlan" } } } },
          "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/destinations": {
      "get": {
        "tags": ["discovery"],
        "operationId": "searchDestinations",
        "summary": "List or filter travel destinations.",
        "parameters": [
          { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": ["weekend", "family", "budget", "romantic", "adventure", "luxury", "cultural"] } },
          { "name": "budget_max", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Max approximate per-person budget (USD)." },
          { "name": "season", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search." }
        ],
        "responses": {
          "200": { "description": "Destinations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationList" } } } }
        }
      }
    },
    "/tours": {
      "get": {
        "tags": ["discovery"],
        "operationId": "searchTours",
        "summary": "List or filter tours.",
        "parameters": [
          { "name": "destination", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "budget_max", "in": "query", "required": false, "schema": { "type": "integer" } }
        ],
        "responses": {
          "200": { "description": "Tours", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TourList" } } } }
        }
      }
    },
    "/excursions": {
      "get": {
        "tags": ["discovery"],
        "operationId": "searchExcursions",
        "summary": "List or filter excursions.",
        "parameters": [
          { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "category", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Excursions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExcursionList" } } } }
        }
      }
    },
    "/create-lead": {
      "post": {
        "tags": ["leads"],
        "operationId": "createLead",
        "summary": "Create a travel request DRAFT (not a booking).",
        "description": "Creates a non-binding travel request draft for an AITravel.az operator to follow up. This NEVER books or confirms anything and NEVER charges money. Use type=vip_manager to request a VIP manager callback.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateLeadRequest" },
              "example": { "type": "lead", "contact": "+994500000000", "destination": "Gabala", "travelers": 2, "message": "Weekend family trip, mid budget" }
            }
          }
        },
        "responses": {
          "200": { "description": "Draft created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } } },
          "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/check-availability": {
      "post": {
        "tags": ["planning"],
        "operationId": "checkAvailability",
        "summary": "Approximate availability check (indicative only).",
        "description": "Returns an indicative availability signal. This is NOT a real-time inventory check and does not reserve anything.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/AvailabilityRequest" },
              "example": { "destination": "Dubai", "dates": "2026-07-10 — 2026-07-15", "travelers": 2 }
            }
          }
        },
        "responses": {
          "200": { "description": "Indicative availability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityResponse" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PlanTripRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "description": "Natural-language trip request." },
          "lang": { "type": "string", "enum": ["az", "ru", "en"], "default": "az" },
          "dates": { "type": "string" },
          "budget": { "type": "string" },
          "travelers": { "type": "string", "default": "2" }
        }
      },
      "TripPlan": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "destinations": { "type": "array", "items": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "days": { "type": "integer" } } } },
          "budget": { "type": "object", "properties": { "currency": { "type": "string" }, "total": { "type": "number" }, "perPerson": { "type": "number" } } },
          "itinerary": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "integer" }, "city": { "type": "string" }, "morning": { "type": "string" }, "afternoon": { "type": "string" }, "evening": { "type": "string" }, "tips": { "type": "string" } } } },
          "hotels": { "type": "array", "items": { "type": "object" } },
          "activities": { "type": "array", "items": { "type": "object" } },
          "disclaimer": { "type": "string", "description": "Prices are approximate and require operator confirmation." }
        }
      },
      "Destination": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" },
          "short_description": { "type": "string" }, "best_for": { "type": "array", "items": { "type": "string" } },
          "approximate_budget_from": { "type": "number" }, "currency": { "type": "string" },
          "duration_options": { "type": "array", "items": { "type": "string" } }, "season": { "type": "string" }, "disclaimer": { "type": "string" }
        }
      },
      "DestinationList": { "type": "object", "properties": { "destinations": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } }, "disclaimer": { "type": "string" } } },
      "Tour": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "title": { "type": "string" }, "destination": { "type": "string" }, "category": { "type": "string" },
          "duration": { "type": "string" }, "approximate_price_from": { "type": "number" }, "currency": { "type": "string" },
          "includes": { "type": "array", "items": { "type": "string" } }, "disclaimer": { "type": "string" }
        }
      },
      "TourList": { "type": "object", "properties": { "tours": { "type": "array", "items": { "$ref": "#/components/schemas/Tour" } }, "disclaimer": { "type": "string" } } },
      "Excursion": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" }, "title": { "type": "string" }, "city": { "type": "string" }, "category": { "type": "string" },
          "duration": { "type": "string" }, "approximate_price_from": { "type": "number" }, "currency": { "type": "string" }, "disclaimer": { "type": "string" }
        }
      },
      "ExcursionList": { "type": "object", "properties": { "excursions": { "type": "array", "items": { "$ref": "#/components/schemas/Excursion" } }, "disclaimer": { "type": "string" } } },
      "CreateLeadRequest": {
        "type": "object",
        "required": ["contact", "message"],
        "properties": {
          "type": { "type": "string", "enum": ["lead", "vip_manager"], "default": "lead" },
          "name": { "type": "string" },
          "contact": { "type": "string", "description": "Phone, email or messenger handle." },
          "destination": { "type": "string" },
          "dates": { "type": "string" },
          "travelers": { "type": "integer" },
          "budget": { "type": "string" },
          "message": { "type": "string" },
          "lang": { "type": "string", "enum": ["az", "ru", "en"] }
        }
      },
      "LeadResponse": {
        "type": "object",
        "properties": {
          "request_id": { "type": "string" },
          "status": { "type": "string", "enum": ["draft_pending_operator"] },
          "message": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      },
      "AvailabilityRequest": {
        "type": "object",
        "required": ["destination"],
        "properties": { "destination": { "type": "string" }, "dates": { "type": "string" }, "travelers": { "type": "integer" } }
      },
      "AvailabilityResponse": {
        "type": "object",
        "properties": {
          "destination": { "type": "string" },
          "status": { "type": "string", "enum": ["approximate"] },
          "available": { "type": "boolean" },
          "note": { "type": "string" },
          "disclaimer": { "type": "string" }
        }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } } }
    }
  }
}