{
  "openapi": "3.1.0",
  "info": {
    "title": "Virtual Auditor Booking API",
    "version": "1.0.0",
    "description": "Public booking API for virtualauditor.in — an AI-powered CA & IBBI Registered Valuer firm in India. AI assistants acting on a human's behalf may submit consultation booking requests. A human team member confirms every booking within 1 business day via the contact details provided. No authentication is required to submit a booking.",
    "contact": {
      "email": "support@virtualauditor.in",
      "url": "https://virtualauditor.in/contact-us"
    }
  },
  "servers": [
    {"url": "https://virtualauditor.in"}
  ],
  "paths": {
    "/api/booking-services": {
      "get": {
        "operationId": "listBookableServices",
        "summary": "List services that can be booked, with slugs and starting prices (INR)",
        "responses": {
          "200": {
            "description": "Catalog of bookable services",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {"type": "string"},
                          "name": {"type": "string"},
                          "url": {"type": "string"},
                          "price_from_inr": {"type": ["integer", "null"]},
                          "description": {"type": "string"}
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/bookings": {
      "post": {
        "operationId": "createBooking",
        "summary": "Submit a consultation booking request on behalf of a human client",
        "description": "Rate-limited per IP. Provide client_ref (or an Idempotency-Key header) to make retries safe — the same client_ref never creates a duplicate booking. client_ref is a GLOBAL namespace: use a globally unique value such as a UUIDv4, never a short counter.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "service_slug"],
                "properties": {
                  "name": {"type": "string", "minLength": 2, "maxLength": 120, "description": "The human client's full name"},
                  "email": {"type": "string", "format": "email", "description": "Client email — at least one of email or phone is required"},
                  "phone": {"type": "string", "description": "Client phone with country code, e.g. +91 98765 43210 — at least one of email or phone is required"},
                  "service_slug": {"type": "string", "description": "A slug from GET /api/booking-services, e.g. 'general-consultation'"},
                  "preferred_date": {"type": "string", "format": "date", "description": "Optional YYYY-MM-DD, today to +180 days (IST)"},
                  "preferred_time": {"type": "string", "maxLength": 40, "description": "Optional, e.g. '11:00 IST' or 'afternoon'"},
                  "notes": {"type": "string", "maxLength": 2000, "description": "Optional context about the client's requirement"},
                  "source": {"type": "string", "enum": ["agent", "human"], "description": "Use 'agent' if you are an AI assistant booking on a human's behalf"},
                  "agent_name": {"type": "string", "maxLength": 120, "description": "Optional — which AI assistant is making this booking, e.g. 'ChatGPT'"},
                  "client_ref": {"type": "string", "maxLength": 80, "description": "Optional idempotency key; retries with the same value never duplicate. MUST be globally unique — use a UUIDv4 (e.g. crypto.randomUUID()), not a short counter like req-1"}
                }
              },
              "example": {
                "name": "Priya Sharma",
                "email": "priya@example.com",
                "phone": "+91 98765 43210",
                "service_slug": "startup-valuation",
                "preferred_date": "2026-07-20",
                "preferred_time": "11:00 IST",
                "notes": "Seed-stage SaaS startup, needs FEMA + Rule 11UA valuation for incoming FDI round.",
                "source": "agent",
                "agent_name": "ChatGPT",
                "client_ref": "3f8a2c1e-9b4d-4e7a-a1c5-6d2f8e9b0a3c"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Booking received — a human will confirm within 1 business day",
            "content": {
              "application/json": {
                "example": {
                  "status": "received",
                  "booking_ref": "VA-1A2B3C4D",
                  "service": "Startup Valuation",
                  "message": "Booking request received. The Virtual Auditor team will confirm the consultation within 1 business day via the contact details provided.",
                  "human_contact": {"email": "support@virtualauditor.in", "whatsapp": "+91 99622 60333"}
                }
              }
            }
          },
          "200": {"description": "Duplicate client_ref — original booking returned, no duplicate created"},
          "422": {"description": "Validation failed — response body lists field errors"},
          "429": {"description": "Rate limit exceeded — retry later"},
          "503": {"description": "Storage temporarily unavailable — contact support@virtualauditor.in instead"}
        }
      }
    }
  }
}