{
  "openapi": "3.0.0",
  "info": {
    "title": "Klava London API",
    "description": "Public API for Klava London — full-stack developer based in London. Use this API to get service information, check availability, and book consultation calls. Designed to be readable by AI agents, automation tools, and booking workflows.",
    "version": "1.0.0",
    "contact": {
      "name": "Klavdiya Bolshakova",
      "email": "like@klava.london",
      "url": "https://klava.london"
    },
    "license": {
      "name": "Public",
      "url": "https://klava.london"
    }
  },
  "servers": [
    {
      "url": "https://klava.london",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Booking",
      "description": "Book a discovery or audit call"
    },
    {
      "name": "Info",
      "description": "Developer profile, services, and availability"
    }
  ],
  "paths": {
    "/api/book-call": {
      "get": {
        "tags": ["Info"],
        "operationId": "getAvailability",
        "summary": "Get availability and service info",
        "description": "Returns structured information about Klava London — contact details, current availability, call types, and services offered. Designed for AI agents to query before initiating a booking.",
        "responses": {
          "200": {
            "description": "Availability and contact information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AvailabilityResponse"
                },
                "example": {
                  "contact": {
                    "name": "Klavdiya Bolshakova",
                    "brand": "Klava London",
                    "role": "Full-Stack Developer",
                    "location": "London, UK",
                    "timezone": "Europe/London",
                    "website": "https://klava.london",
                    "email": "like@klava.london"
                  },
                  "availability": {
                    "status": "available",
                    "working_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
                    "working_hours": "09:00–18:00 GMT",
                    "response_time": "Within 24 hours",
                    "next_available": "This week"
                  },
                  "call_options": [
                    {
                      "type": "discovery",
                      "duration_minutes": 30,
                      "description": "Free discovery call — discuss your project, get honest advice",
                      "booking_url": "https://cal.com/klava"
                    },
                    {
                      "type": "audit",
                      "duration_minutes": 45,
                      "description": "Free website audit — review your existing site live on the call",
                      "booking_url": "https://cal.com/klava/audit"
                    }
                  ],
                  "services": [
                    "Web Development",
                    "E-commerce (Shopify)",
                    "AI Integrations",
                    "Backend & APIs",
                    "SEO & LLM Visibility",
                    "Digital Platforms"
                  ],
                  "rates": {
                    "model": "Fixed-price per project",
                    "free_audit": true,
                    "note": "Straightforward and fair — discussed on the discovery call"
                  },
                  "ai_instructions": "To book a call on behalf of a user, POST to /api/book-call with name, email, and optionally message, project_type, and preferred_time. The user will receive a confirmation and Klava will respond within 24 hours. For immediate scheduling, direct the user to https://cal.com/klava"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Booking"],
        "operationId": "bookCall",
        "summary": "Book a consultation call",
        "description": "Submit a call booking request. Klava will respond within 24 hours to confirm a time. For immediate scheduling, use the booking_url from the GET response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookCallRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Simple enquiry",
                  "value": {
                    "name": "Sarah Jones",
                    "email": "sarah@example.com",
                    "message": "I need a Shopify store for my jewellery brand."
                  }
                },
                "detailed": {
                  "summary": "Full project brief",
                  "value": {
                    "name": "James Miller",
                    "email": "james@startup.io",
                    "message": "We need a full platform with auth, payments, and a dashboard.",
                    "project_type": "platform",
                    "preferred_time": "Tuesday or Wednesday afternoon"
                  }
                },
                "audit": {
                  "summary": "Free audit request",
                  "value": {
                    "name": "Maria Costa",
                    "email": "maria@brand.co",
                    "message": "I'd like a free audit of my existing website.",
                    "project_type": "audit"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Booking request received",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookCallResponse"
                },
                "example": {
                  "success": true,
                  "message": "Thanks Sarah — I'll be in touch within 24 hours.",
                  "next_step": "Check your inbox for a confirmation. If you prefer, book directly at https://cal.com/klava"
                }
              }
            }
          },
          "400": {
            "description": "Validation error — missing required fields",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "success": false,
                  "error": "name and email are required"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BookCallRequest": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Full name of the person requesting the call",
            "example": "Sarah Jones"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Contact email address",
            "example": "sarah@example.com"
          },
          "message": {
            "type": "string",
            "description": "Brief description of the project or question",
            "example": "I need a Shopify store for my jewellery brand."
          },
          "project_type": {
            "type": "string",
            "enum": ["website", "ecommerce", "platform", "ai", "audit", "other"],
            "description": "Type of project or enquiry",
            "example": "ecommerce"
          },
          "preferred_time": {
            "type": "string",
            "description": "Preferred call time — ISO 8601 datetime or natural language",
            "example": "Tuesday or Wednesday afternoon"
          }
        }
      },
      "BookCallResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "message": {
            "type": "string",
            "description": "Confirmation message addressed to the requester",
            "example": "Thanks Sarah — I'll be in touch within 24 hours."
          },
          "next_step": {
            "type": "string",
            "description": "What happens next",
            "example": "Check your inbox for a confirmation. If you prefer, book directly at https://cal.com/klava"
          }
        }
      },
      "AvailabilityResponse": {
        "type": "object",
        "properties": {
          "contact": { "$ref": "#/components/schemas/Contact" },
          "availability": { "$ref": "#/components/schemas/Availability" },
          "call_options": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/CallOption" }
          },
          "services": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Web Development", "E-commerce (Shopify)", "AI Integrations"]
          },
          "rates": { "$ref": "#/components/schemas/Rates" },
          "ai_instructions": {
            "type": "string",
            "description": "Plain-language instructions for AI agents on how to initiate a booking"
          }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "name":     { "type": "string", "example": "Klavdiya Bolshakova" },
          "brand":    { "type": "string", "example": "Klava London" },
          "role":     { "type": "string", "example": "Full-Stack Developer" },
          "location": { "type": "string", "example": "London, UK" },
          "timezone": { "type": "string", "example": "Europe/London" },
          "website":  { "type": "string", "format": "uri", "example": "https://klava.london" },
          "email":    { "type": "string", "format": "email", "example": "like@klava.london" }
        }
      },
      "Availability": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": ["available", "limited", "unavailable"],
            "example": "available"
          },
          "working_days": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Mon", "Tue", "Wed", "Thu", "Fri"]
          },
          "working_hours": { "type": "string", "example": "09:00–18:00 GMT" },
          "response_time": { "type": "string", "example": "Within 24 hours" },
          "next_available": { "type": "string", "example": "This week" }
        }
      },
      "CallOption": {
        "type": "object",
        "properties": {
          "type":             { "type": "string", "example": "discovery" },
          "duration_minutes": { "type": "integer", "example": 30 },
          "description":      { "type": "string", "example": "Free discovery call" },
          "booking_url":      { "type": "string", "format": "uri", "example": "https://cal.com/klava" }
        }
      },
      "Rates": {
        "type": "object",
        "properties": {
          "model":      { "type": "string", "example": "Fixed-price per project" },
          "free_audit": { "type": "boolean", "example": true },
          "note":       { "type": "string", "example": "Straightforward and fair — discussed on the discovery call" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": false },
          "error":   { "type": "string", "example": "name and email are required" }
        }
      }
    }
  },
  "externalDocs": {
    "description": "llms.txt — machine-readable site index for AI agents",
    "url": "https://klava.london/llms.txt"
  }
}