{"openapi":"3.1.0","info":{"title":"Entervista","version":"0.2.0","description":"Local businesses set up for AI agents. Search, read real prices, order/quote/book, human approves, business confirms."},"servers":[{"url":"https://entervista.ai/api/v1"}],"paths":{"/photos":{"post":{"operationId":"upload_photo","summary":"Upload a photo of the problem; put the returned url in photos[] of place_service_request.","requestBody":{"content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}},"image/png":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","required":["image_base64"],"properties":{"image_base64":{"type":"string"},"media_type":{"type":"string"}}}}}},"responses":{"201":{"description":"{id, url, bytes}"}}}},"/businesses":{"get":{"operationId":"search_businesses","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"zip","in":"query","schema":{"type":"string"}},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"open_now","in":"query","schema":{"type":"boolean"}},{"name":"accepts","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Results"}}}},"/businesses/{slug}":{"get":{"operationId":"get_business","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Profile"},"404":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}}}}},"/businesses/{slug}/services":{"get":{"operationId":"get_services","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Services with pricing mode and required intake fields"}}}},"/businesses/{slug}/service-area":{"get":{"operationId":"check_service_area","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"zip","in":"query","required":true,"schema":{"type":"string"}},{"name":"emergency","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"{serves, reason, service_zips, alternatives}"}}}},"/businesses/{slug}/services/{sku}/requirements":{"get":{"operationId":"get_service_requirements","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"sku","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"required_fields, optional_fields, flow, what_happens_next"},"404":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}}}}},"/businesses/{slug}/requests":{"post":{"operationId":"place_service_request","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["customer"],"properties":{"service_sku":{"type":"string"},"description":{"type":"string"},"intake_answers":{"type":"object","additionalProperties":true},"customer":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["line1","zip"]},"notes":{"type":"string"}}},"preferred_time":{"type":"string"},"slot_start":{"type":"string"},"urgency":{"type":"string","enum":["emergency","today","this_week","flexible"]},"photos":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Draft (awaiting_customer_approval | quote_ready | quote_requested) with ref, customer_token, amount, offered_slots"},"400":{"description":"MISSING_INFORMATION (missing[]), OUT_OF_SERVICE_AREA (alternatives), SERVICE_NOT_OFFERED (closest), CLOSED (next_open)"}}}},"/businesses/{slug}/availability":{"get":{"operationId":"get_availability","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"date","in":"query","schema":{"type":"string"}},{"name":"days","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Slots"}}}},"/businesses/{slug}/orders":{"post":{"operationId":"place_order","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["items","fulfillment","customer"],"properties":{"items":{"type":"array","items":{"type":"object","required":["sku"],"properties":{"sku":{"type":"string"},"qty":{"type":"integer"},"size":{"type":"string"},"add_ons":{"type":"array","items":{"type":"string"}},"notes":{"type":"string"}}}},"fulfillment":{"type":"string","enum":["pickup","delivery"]},"customer":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["line1","zip"]},"notes":{"type":"string"}}},"requested_time":{"type":"string"}}}}}},"responses":{"200":{"description":"Draft order awaiting customer approval; includes ref, total, customer_token"},"400":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}}}}},"/businesses/{slug}/quotes":{"post":{"operationId":"request_quote","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["description","customer"],"properties":{"description":{"type":"string"},"service_sku":{"type":"string"},"customer":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["line1","zip"]},"notes":{"type":"string"}}},"urgency":{"type":"string","enum":["emergency","today","this_week","flexible"]},"preferred_times":{"type":"array","items":{"type":"string"}},"photos":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Quote request (instant quote when available)"},"400":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}}}}},"/businesses/{slug}/bookings":{"post":{"operationId":"book_slot","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["service_sku","slot_start","customer"],"properties":{"service_sku":{"type":"string"},"slot_start":{"type":"string"},"customer":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"}},"required":["line1","zip"]},"notes":{"type":"string"}}},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Draft booking awaiting approval"},"400":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}}}}},"/requests/{ref}":{"get":{"operationId":"get_request_status","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}},{"name":"customer_token","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Status"},"404":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}}}}},"/requests/{ref}/approve":{"post":{"operationId":"approve_request","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["customer_token"],"properties":{"customer_token":{"type":"string"},"slot_start":{"type":"string"},"payment_token":{"type":"string","description":"Optional Stripe shared payment token (spt_...) from the assistant's wallet; pays in-chat instead of returning payment_url"}}}}}},"responses":{"200":{"description":"Approved; confirmed/booked, awaiting business, or awaiting_payment with payment_url"},"400":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}}}}},"/requests/{ref}/pay":{"post":{"operationId":"pay_request","summary":"Pay an awaiting_payment request with a Stripe shared payment token","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["customer_token","payment_token"],"properties":{"customer_token":{"type":"string"},"payment_token":{"type":"string","description":"spt_..."}}}}}},"responses":{"200":{"description":"Paid; request is booked/completed"},"400":{"description":"Structured error an agent can act on","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"hint":{"type":"string"},"alternatives":{"type":"array"}}}}}}}},"402":{"description":"PAYMENT_TOKEN_REJECTED; payment_url is the fallback"}}}},"/requests/{ref}/cancel":{"post":{"operationId":"cancel_request","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["customer_token"],"properties":{"customer_token":{"type":"string"},"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Cancelled"}}}}}}