{"openapi":"3.1.0","info":{"title":"WhichAgent Beauty Category API","version":"1.0.0","description":"Deterministic API for Orange County barbershops. Availability and booking are official-provider handoffs only."},"servers":[{"url":"https://whichagent.ai"}],"paths":{"/api/categories/beauty/{verb}":{"post":{"parameters":[{"name":"verb","in":"path","required":true,"schema":{"enum":["search","details","compare","availability","book"]}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Category response","content":{"application/json":{"schema":{"type":"object","required":["meta"],"properties":{"data":{},"error":{"type":"object"},"meta":{"type":"object","required":["request_id","api_version","category","source"]}}}}}},"400":{"description":"Structured input error","content":{"application/json":{"schema":{"type":"object","required":["meta"],"properties":{"data":{},"error":{"type":"object"},"meta":{"type":"object","required":["request_id","api_version","category","source"]}}}}}},"404":{"description":"Structured business error","content":{"application/json":{"schema":{"type":"object","required":["meta"],"properties":{"data":{},"error":{"type":"object"},"meta":{"type":"object","required":["request_id","api_version","category","source"]}}}}}}}}}},"components":{"schemas":{"CategorySchema":{"name":"whichagent-beauty","version":"1.0.0","api_version":"1","category_id":"orange-county-barbershops","scope":"Orange County, California barbershops from publicly accessible business and directory sources. This first beauty subcategory includes barbershops only.","action_policy":"deterministic_handoff_only","commands":{"search":{"input":{"city":"Optional Orange County city name, such as Irvine, Orange, or Santa Ana.","service":"Optional published barbershop service, such as haircut, beard trim, or fade.","availability_class":"Optional availability class: live, booking-site, or none."},"output":"Returns normalized, source-linked business records for Orange County, CA barbershops.","useWhen":"the user wants to find or compare local Orange County barbershops with constraints such as city, published service, or availability class.","doNotUseWhen":"the user needs beauty categories beyond the published barbershop subcategory, results outside Orange County, guaranteed real-time appointment slots or prices, payment, or a completed booking."},"details":{"input":{"business_id":"Required stable business ID returned by search, for example crowns-barbershop."},"output":"Returns a normalized, source-linked business record for one Orange County, CA barbershop.","useWhen":"the user wants published services, contact information, availability class, or source links for a barbershop selected from search.","doNotUseWhen":"the user needs beauty categories beyond the published barbershop subcategory, a business outside Orange County, a guaranteed live appointment slot or price, payment, or a completed booking."},"compare":{"input":{"business_ids":"Required array or comma-separated list of at least two stable business IDs returned by search.","criteria":"Optional array or comma-separated list of comparison fields: city, services, availability_class, capabilities."},"output":"Returns a normalized, source-linked comparison of selected Orange County, CA barbershops.","useWhen":"the user wants to compare two or more search results on city, published services, availability class, or published handoff capabilities.","doNotUseWhen":"the user needs beauty categories beyond barbershops, results outside Orange County, guaranteed real-time slots or prices, payment, or a completed booking."},"availability":{"input":{"business_id":"Required stable business ID returned by search.","service":"Optional published service requested, such as haircut or beard trim.","appointment_date":"Optional desired appointment date in YYYY-MM-DD format."},"output":"Returns a normalized availability handoff for a source-linked Orange County, CA barbershop, including availability class live, booking-site, or none; it does not guarantee a slot.","useWhen":"the user has selected a barbershop and wants its provider handoff to check a service and, optionally, an appointment date.","doNotUseWhen":"the user needs a guaranteed live appointment slot or price, beauty services beyond barbershops, results outside Orange County, payment, or a completed booking; availability only returns a class and provider handoff."},"book":{"input":{"business_id":"Required stable business ID returned by search.","service":"Optional published service requested, such as haircut or beard trim.","appointment_date":"Optional desired appointment date in YYYY-MM-DD format."},"output":"Returns a normalized booking handoff link for a source-linked Orange County, CA barbershop; it never creates or confirms an appointment.","useWhen":"the user has selected a barbershop and wants its official booking or contact handoff for a service and, optionally, an appointment date.","doNotUseWhen":"the user needs WhichAgent to create or confirm an appointment, take payment, guarantee a live slot or price, find beauty categories beyond barbershops, or serve locations outside Orange County."}},"envelope":{"success":{"data":"object","meta":{"request_id":"uuid","api_version":"1","category":"orange-county-barbershops","source":"string"}},"failure":{"error":{"code":"string","message":"string","field_errors":"object|null"},"meta":"same as success"}}}}}}