{
  "openapi":"3.1.0",
  "info":{"title":"Rosedell guest-delegated stay requests","version":"1.4.0",
    "description":"Guest-authorized exact-stay requests. Returning guests create a 24-hour delegation from their authenticated confirmed reservation. When the public catalog advertises firstTimeGuestDelegationSupported, first-time guests may instead verify email in the same browser and explicitly approve an exact stay on the hosted human permission page. The agent cannot create that permission, submit a guest email address, or complete verification for the guest through this API. The guest privately supplies the resulting request ID and bearer key. For an existing inquiry or reservation, whether originally submitted by the guest or an assistant, a verified guest may separately grant 30-day read-only status access from Guest Messages and renew or revoke it for the same request. Ordinary inquiries receive a stable status request ID only after consent; this does not fabricate an agent submission. Renewal rotates the status key without creating a new inquiry; normal browser sign-out does not revoke it. One request ID is one idempotent non-binding inquiry. Host approval, guest agreement, identity verification and guest payment remain separate. No reservations, inventory holds, payments or door credentials can be created through this API. Production is disabled unless both GuestAgentRequests gates are approved; first-time permission also requires its separate gate and valid verification email settings."},
  "servers":[{"url":"https://rosedellestate.com"}],
  "security":[{"guestDelegation":[]}],
  "paths":{"/api/guest/v1/requests/{requestId}":{
    "parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f0-9]{32}$"},"description":"Request ID supplied by the guest with the delegation key. Never put the key in a URL."}],
    "post":{"operationId":"submitDelegatedStayRequest","description":"Requires the 24-hour submission permission; a read-only status key is never accepted, even for an already submitted request. Submit exactly the guest-authorized stay. Retry this same ID and identical body after timeout/503; retries return the same inquiry without duplicate notifications. Different terms require new guest permission. Unknown availability remains a non-binding host-review request, never an inventory promise.",
      "requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stay"}}}},
      "responses":{"201":{"description":"New inquiry saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"200":{"description":"Already submitted; current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/Unavailable"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"description":"Body exceeds 2048 bytes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Use application/json","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Retry"}}},
    "get":{"operationId":"readDelegatedStayRequest","security":[{"guestDelegation":[]},{"guestStatusRead":[]}],"description":"Read only this request using a current submission permission or separately guest-approved 30-day status key. Status permission can refer to an ordinary inquiry or its reservation even if an assistant never submitted it. Poll no more than once every five minutes and honor Retry-After. On 401 stop polling and ask the guest to renew status access for this same request at https://rosedellestate.com/guest/messages; never create another inquiry or retry POST with a status key. Status is advisory and can change. Offer revision and expiry identify the latest offer; they cannot be accepted through this API. A confirmed response describes an existing confirmed booking and does not authorize changing it.",
      "responses":{"200":{"description":"Current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"400":{"$ref":"#/components/responses/Invalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/Unavailable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Retry"}}}
  }},
  "components":{
    "securitySchemes":{"guestDelegation":{"type":"http","scheme":"bearer","description":"Guest-issued, revocable, 24-hour opaque key. Scope: one exact new inquiry and its status. No cookies, staff credentials or query credentials are accepted."},"guestStatusRead":{"type":"http","scheme":"bearer","description":"Separate guest-approved 30-day read-only opaque key, issued/renewed/revoked by the signed-in guest at https://rosedellestate.com/guest/messages. Only GET for the existing request; no POST, messages, booking changes or payment authority. Each renewal replaces the old key, preserving the request ID. Expiry is supplied in the guest-shared permission. Signing out does not revoke it. No credential in URLs, logs or query parameters."}},
    "schemas":{
      "Stay":{"type":"object","additionalProperties":false,"required":["unit","arrival","departure","guests"],"properties":{"unit":{"type":"string","enum":["a","b","c"]},"arrival":{"type":"string","format":"date"},"departure":{"type":"string","format":"date"},"guests":{"type":"integer","minimum":1,"maximum":6}}},
      "Status":{"type":"object","additionalProperties":true,"required":["apiVersion","requestId","state","nextAction","hostReviewRequired","bookingConfirmed","offerRevision","offerExpiresAt","version"],"properties":{
        "apiVersion":{"const":"1"},"requestId":{"type":"string"},"state":{"type":"string","enum":["request_received","host_review","closed","offer_ready","offer_expired","reserved_awaiting_payment","awaiting_payment","confirmed","cancelled"]},"nextAction":{"type":"string","readOnly":true,"enum":["wait_for_host","guest_review_offer","contact_host","guest_review_payment_schedule","guest_complete_payment","guest_view_reservation","none"],"description":"Advisory human next step, never agent execution authority. request_received/host_review: wait_for_host; offer_ready: guest_review_offer; offer_expired: contact_host; reserved_awaiting_payment: guest_review_payment_schedule; awaiting_payment: guest_complete_payment; confirmed: guest_view_reservation; closed/cancelled: none. Only a generic guest sign-in or public contact URL is supplied through guestNextStep; no payment or private guest URLs are supplied."},"hostReviewRequired":{"type":"boolean"},"bookingConfirmed":{"type":"boolean"},"guestNextStep":{"oneOf":[{"$ref":"#/components/schemas/GuestNextStep"},{"type":"null"}],"readOnly":true,"description":"Optional human-only guidance. Give this link to the traveler; do not sign in, request their email link, accept terms or pay for them. No access is granted by the URL. Closed/cancelled requests have null; older responses may omit this field. offerExpiresAt is not a deferred payment deadline."},"offerRevision":{"type":["integer","null"]},"offerExpiresAt":{"type":["string","null"],"format":"date-time"},"version":{"type":"string","description":"Opaque revision of this status. Never a payment or acceptance credential."}}},
      "GuestNextStep":{"type":"object","additionalProperties":true,"required":["title","instructions","url","linkLabel","requiresGuestSignIn"],"properties":{"title":{"type":"string"},"instructions":{"type":"string"},"url":{"type":"string","format":"uri","enum":["https://rosedellestate.com/guest/messages","https://rosedellestate.com/book#guest-contact"]},"linkLabel":{"type":"string"},"requiresGuestSignIn":{"type":"boolean"}}},
      "Error":{"type":"object","required":["apiVersion","code","message"],"properties":{"apiVersion":{"const":"1"},"code":{"type":"string"},"message":{"type":"string"}}}
    },
    "responses":{
      "Invalid":{"description":"Invalid JSON, fields, stay, query parameters or non-HTTPS request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Unauthorized":{"description":"Unknown, expired, revoked, suspended, cross-request or wrong-operation permission. For existing requests ask the guest to renew read-only access in Guest Messages; keep the same request ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Unavailable":{"description":"Feature paused, not submitted yet, or removed inquiry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Conflict":{"description":"scope_conflict or dates_unavailable. Obtain new guest permission for different terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "RateLimited":{"description":"At most 20 requests/minute per client address; no queue","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"60 seconds"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Retry":{"description":"Storage/availability unavailable; after 60 seconds retry the same operation and request ID. GET callers must retry GET only, never POST. POST callers retain the identical body. Never create another request","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}
    }
  }
}