{"openapi":"3.1.0","info":{"title":"ReserveVia Agent API","version":"v1","description":"AI-native restaurant discovery, live availability, safe holds, and reservation management."},"servers":[{"url":"/api/v1","description":"Application-compatible API path"}],"security":[{"bearerAuth":[]}],"paths":{"/businesses":{"get":{"operationId":"listBusinesses","security":[],"parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/PageToken"},{"$ref":"#/components/parameters/ChangesToken"}],"responses":{"200":{"description":"OpenAI-compatible business feed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessFeed"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/restaurants/search":{"get":{"operationId":"searchRestaurants","security":[],"parameters":[{"name":"query","in":"query","schema":{"type":"string"}},{"name":"latitude","in":"query","schema":{"type":"number"}},{"name":"longitude","in":"query","schema":{"type":"number"}},{"name":"radius","in":"query","schema":{"type":"number","maximum":100}},{"name":"locality","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Published restaurant matches"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/restaurants/{restaurant_id}":{"get":{"operationId":"getRestaurant","security":[],"parameters":[{"$ref":"#/components/parameters/RestaurantId"}],"responses":{"200":{"description":"Safe public restaurant details"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/restaurants/{restaurant_id}/availability":{"get":{"operationId":"refreshAvailability","security":[],"parameters":[{"$ref":"#/components/parameters/RestaurantId"},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"party_size","in":"query","required":true,"schema":{"type":"integer","minimum":1}},{"name":"preferred_time","in":"query","schema":{"type":"string","pattern":"^\\d{2}:\\d{2}$"}}],"responses":{"200":{"description":"Live availability"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/reservation-holds":{"post":{"operationId":"createReservationHold","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HoldRequest"}}}},"responses":{"201":{"description":"Short-lived hold"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/reservations":{"post":{"operationId":"createReservation","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/UserConfirmed"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationRequest"}}}},"responses":{"201":{"description":"One reservation and scoped management token"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/reservations/{reservation_id}/confirmation":{"get":{"operationId":"getReservationConfirmation","parameters":[{"$ref":"#/components/parameters/ReservationId"},{"$ref":"#/components/parameters/ManagementToken"}],"responses":{"200":{"description":"Private confirmation"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/reservations/{reservation_id}":{"patch":{"operationId":"modifyReservation","parameters":[{"$ref":"#/components/parameters/ReservationId"},{"$ref":"#/components/parameters/ManagementToken"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationPatch"}}}},"responses":{"200":{"description":"Modified reservation"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/reservations/{reservation_id}/cancel":{"post":{"operationId":"cancelReservation","parameters":[{"$ref":"#/components/parameters/ReservationId"},{"$ref":"#/components/parameters/ManagementToken"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Cancelled reservation"},"409":{"$ref":"#/components/responses/Conflict"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Hashed ReserveVia API client credential."}},"parameters":{"RestaurantId":{"name":"restaurant_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ReservationId":{"name":"reservation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}},"ManagementToken":{"name":"X-Reservation-Management-Token","in":"header","required":true,"schema":{"type":"string"}},"UserConfirmed":{"name":"x-reservevia-user-confirmed","in":"header","required":true,"schema":{"type":"string","enum":["true"]}},"PageSize":{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},"PageToken":{"name":"page_token","in":"query","schema":{"type":"string"}},"ChangesToken":{"name":"changes_token","in":"query","schema":{"type":"string"}}},"schemas":{"Business":{"type":"object","required":["id","name","address","location","phone_number","website_url","platform_url"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"address":{"type":"object"},"location":{"type":"object","required":["latitude","longitude"]},"phone_number":{"type":["string","null"]},"website_url":{"type":["string","null"],"format":"uri"},"platform_url":{"type":"string","format":"uri"}}},"BusinessFeed":{"type":"object","required":["businesses","checksum"],"properties":{"businesses":{"type":"array","items":{"$ref":"#/components/schemas/Business"}},"next_page_token":{"type":["string","null"]},"changes_token":{"type":"string"},"checksum":{"type":"string"}}},"HoldRequest":{"type":"object","required":["restaurant_id","date","party_size"],"properties":{"restaurant_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date"},"party_size":{"type":"integer","minimum":1},"preferred_time":{"type":"string"},"reservation_area_id":{"type":"string","format":"uuid"},"ttl_seconds":{"type":"integer","minimum":30,"maximum":600}}},"ReservationRequest":{"type":"object","required":["restaurant_id","date","time","party_size","guest"],"properties":{"restaurant_id":{"type":"string","format":"uuid"},"hold_id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date"},"time":{"type":"string"},"party_size":{"type":"integer","minimum":1},"guest":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string","format":"email"},"notes":{"type":"string"}}}}},"ReservationPatch":{"type":"object","properties":{"date":{"type":"string","format":"date"},"time":{"type":"string"},"party_size":{"type":"integer","minimum":1},"guest":{"type":"object"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"suggested_action":{"type":"string"},"request_id":{"type":"string"}}}}}},"responses":{"RateLimited":{"description":"Rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"Reservation or availability conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}