{"openapi":"3.1.0","info":{"title":"EassyLife Public & Agent API","version":"1.0.0","description":"Official API for EassyLife (https://www.eassy.life). Connects customers and AI agents with verified home services across India — AC maintenance, deep cleaning, salon, pest control, appliance repairs, warranties, and more.","termsOfService":"https://www.eassy.life/terms-conditions","contact":{"name":"EassyLife Developer Support","url":"https://www.eassy.life/docs","email":"support@eassylife.in"},"license":{"name":"Proprietary","url":"https://www.eassy.life/terms-conditions"}},"servers":[{"url":"https://www.eassy.life","description":"Production Server"},{"url":"http://localhost:3000","description":"Local Development / Sandbox"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["read:services","read:locations"]}],"paths":{"/api/v1/services":{"get":{"operationId":"listServices","summary":"List available home services","description":"Returns a curated list of verified home services offered by EassyLife, optionally filtered by category or city.","tags":["Services"],"parameters":[{"name":"category","in":"query","required":false,"description":"Filter services by category slug (e.g., \"cleaning\", \"ac-services\", \"salon\", \"appliance-repair\")","schema":{"type":"string"}},{"name":"city","in":"query","required":false,"description":"Filter services by Indian city (e.g., \"Mumbai\", \"Delhi NCR\", \"Bengaluru\", \"Pune\")","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of items to return (default 20, max 100)","schema":{"type":"integer","default":20,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"List of services retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceListResponse"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/services/{slug}":{"get":{"operationId":"getServiceDetails","summary":"Get details for a specific service","description":"Retrieves detailed specifications, inclusion/exclusion checklists, pricing packages, and warranty terms for a specific service slug.","tags":["Services"],"parameters":[{"name":"slug","in":"path","required":true,"description":"The unique slug identifier of the service (e.g., \"ac-services\", \"home-deep-cleaning\")","schema":{"type":"string"}}],"responses":{"200":{"description":"Detailed service object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceDetailResponse"}}}},"404":{"description":"Service not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/categories":{"get":{"operationId":"listCategories","summary":"List all service categories","description":"Returns all top-level service categories (Cleaning, AC & Appliances, Salon & Beauty, Repairs, Pest Control).","tags":["Categories"],"responses":{"200":{"description":"List of categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryListResponse"}}}}}}},"/api/v1/locations":{"get":{"operationId":"listServiceableLocations","summary":"List serviceable cities and check pin codes","description":"Returns the active cities and coverage areas where EassyLife verified professionals operate across India.","tags":["Locations"],"parameters":[{"name":"pincode","in":"query","required":false,"description":"6-digit Indian postal PIN code to check coverage for","schema":{"type":"string","pattern":"^[1-9][0-9]{5}$"}}],"responses":{"200":{"description":"Coverage and serviceable locations response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationListResponse"}}}}}}},"/api/v1/estimate":{"post":{"operationId":"calculatePriceEstimate","summary":"Calculate price estimate for a service package","description":"Calculates an instant transparent price estimate given service slug, package details, addons, and city.","tags":["Pricing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateRequest"}}}},"responses":{"200":{"description":"Transparent price calculation breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EstimateResponse"}}}},"400":{"description":"Invalid calculation parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/mcp":{"post":{"operationId":"mcpJsonRpcEndpoint","summary":"Streamable HTTP Model Context Protocol (MCP) endpoint","description":"Processes JSON-RPC 2.0 requests from AI agents (Claude, ChatGPT, OpenRouter, cursor) using Streamable HTTP transport to call EassyLife tools.","tags":["MCP"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC response or Streamable event stream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpJsonRpcResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Self-serve API key. For testing/sandbox mode, use key: \"test_key_eassylife_demo\"."},"OAuth2":{"type":"oauth2","description":"Standard OAuth 2.0 Authorization Server","flows":{"clientCredentials":{"tokenUrl":"https://www.eassy.life/api/auth/token","scopes":{"read:services":"Read available services, categories, and service details","read:locations":"Query serviceable cities, hubs, and coverage pin codes","estimate:pricing":"Generate quotes and pricing estimates for booking configurations","book:service":"Create and manage service booking appointments","read:orders":"Inspect existing customer orders and status updates"}}}}},"schemas":{"ServiceSummary":{"type":"object","required":["id","slug","name","category","startingPrice","currency"],"properties":{"id":{"type":"string","description":"Unique service ID"},"slug":{"type":"string","description":"URL slug for the service"},"name":{"type":"string","description":"Human-readable service title"},"category":{"type":"string","description":"Parent category name"},"description":{"type":"string","description":"Summary of what the service entails"},"startingPrice":{"type":"number","description":"Starting price in INR"},"currency":{"type":"string","default":"INR","description":"Currency code"},"isPopular":{"type":"boolean","description":"Whether this is a top-booked service"},"rating":{"type":"number","description":"Average customer rating out of 5"},"reviewsCount":{"type":"integer","description":"Number of verified customer reviews"},"url":{"type":"string","description":"Canonical webpage URL for booking"}}},"ServiceListResponse":{"type":"object","required":["success","data","meta"],"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ServiceSummary"}},"meta":{"type":"object","required":["total","count"],"properties":{"total":{"type":"integer","example":15},"count":{"type":"integer","example":15},"city":{"type":"string","example":"Mumbai"}}}}},"ServiceDetailResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","required":["id","slug","name","category","packages"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"longDescription":{"type":"string"},"inclusions":{"type":"array","items":{"type":"string"}},"exclusions":{"type":"array","items":{"type":"string"}},"warrantyDays":{"type":"integer","example":30},"packages":{"type":"array","items":{"type":"object","properties":{"packageId":{"type":"string"},"name":{"type":"string"},"price":{"type":"number"},"durationMinutes":{"type":"integer"}}}}}}}},"CategoryListResponse":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","required":["id","name","slug","servicesCount"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"servicesCount":{"type":"integer"}}}}}},"LocationListResponse":{"type":"object","required":["success","cities"],"properties":{"success":{"type":"boolean","example":true},"cities":{"type":"array","items":{"type":"string"}},"pincodeChecked":{"type":"string"},"isServiceable":{"type":"boolean"}}},"EstimateRequest":{"type":"object","required":["serviceSlug","city"],"properties":{"serviceSlug":{"type":"string","example":"ac-services"},"city":{"type":"string","example":"Mumbai"},"quantity":{"type":"integer","default":1,"minimum":1},"packageType":{"type":"string","example":"deep-clean"},"pincode":{"type":"string","example":"400001"}}},"EstimateResponse":{"type":"object","required":["success","estimate"],"properties":{"success":{"type":"boolean","example":true},"estimate":{"type":"object","required":["basePrice","taxes","totalPrice","currency","advancePaymentPercentage"],"properties":{"serviceSlug":{"type":"string"},"serviceName":{"type":"string"},"basePrice":{"type":"number","example":499},"taxes":{"type":"number","example":89.82},"totalPrice":{"type":"number","example":588.82},"currency":{"type":"string","example":"INR"},"advancePaymentPercentage":{"type":"number","example":10},"doorstepPaymentAmount":{"type":"number","example":529.94},"warranty":{"type":"string","example":"30-day service warranty"}}}}},"McpJsonRpcRequest":{"type":"object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"method":{"type":"string","example":"tools/call"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"params":{"type":"object"}}},"McpJsonRpcResponse":{"type":"object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_PARAMETER"},"message":{"type":"string","example":"The provided parameters were invalid"},"hint":{"type":"string","example":"Check https://www.eassy.life/docs for endpoint parameters"},"sitemap":{"type":"string","example":"https://www.eassy.life/sitemap.xml"},"llms":{"type":"string","example":"https://www.eassy.life/llms.txt"},"docs":{"type":"string","example":"https://www.eassy.life/docs"}}}}}}}}